#
# CDDL HEADER START
#
# The contents of this file are subject to the terms of the
# Common Development and Distribution License (the "License").
# You may not use this file except in compliance with the License.
#
# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
# or http://www.opensolaris.org/os/licensing.
# See the License for the specific language governing permissions
# and limitations under the License.
#
# When distributing Covered Code, include this CDDL HEADER in each
# file and include the License file at usr/src/OPENSOLARIS.LICENSE.
# If applicable, add the following below this CDDL HEADER, with the
# fields enclosed by brackets "[]" replaced with your own identifying
# information: Portions Copyright [yyyy] [name of copyright owner]
#
# CDDL HEADER END
#

#
# Copyright 2008 Sun Microsystems, Inc.  All rights reserved.
# Use is subject to license terms.
#
# ident	"@(#)README	1.8	08/11/21 SMI"
#

This directory contains a set of tools to set up Kerberos V5
environment for testing purposes. This file describes what they
are, how to use them, how to install them, etc.

Krb5tools
=========

krb5tools includes the following tools currently:

    kdccfg        - set up specified host as KDC
    kdc_clientcfg - set up specified host as KDC client
    krb5nfscfg    - set up specified host for kerberized NFS
    princadm      - create or delete principals
    kinfo	  - print Kerberos configuration, principals,
		    cached tickets, and logs, etc.

These tools can work on either localhost or a remote host. If a host
is specified, the requested operation is performed on that host;
otherwise, localhost is used.

For flexibility, each tool focuses on a single task and can be used
together. For example, kdc_clientcfg uses an existing KDC and sets
up a host as that KDC's client. It is user's responsibility to
set up that KDC, That can be done, e.g., by calling kdccfg.

For another example, krb5nfscfg enables kerverized NFS support on
a KDC client.  It is user's responsibility to set up that host as
a KDC client before calling krb5nfscfg. That can be done, e.g., by
calling kdc_clientcfg.

That is, conceptually, these tools are designed to be stacked atop
each other, as illustrated in the diagram below:

    +-----------------+
    |  krb5nfscfg     |
    +-----------------+
    |  kdc_clientcfg  |
    +-----------------+
    |  kdccfg         |
    +-----------------+

User are supposed to use these tool from bottom up when setting up
a host, and from top down when cleaning up that host.


Synopses and Usages
===================

All tools (except kinfo) have -s and -c option, which means setup
and cleanup, respectively. User should specify either -s or -c
to use them; otherwise it is considered as an usage error.

Below are the detailed description for each tool:

1) kdccfg

kdccfg <-s|-c> [-d domain_list] [host]
    -s     	set up the host as KDC
    -c     	clean up the host with previous KDC configuration
    -d      	a comma separated list of additional DNS domains that
                will be mapped to the same realm. This is optional.
		It is only needed if the realm contains multiple domains.
    host   	the host to be set up as KDC (if -s is specified) or
		to be clean up (if -c is specified). This is optional.
           	If no host is specified, localhost will be used.

kdccfg sets up the specified host as KDC. If the host isn't
specified, localhost is used.

To set up KDC, the tool does the following:

    - create /etc/resolv.conf if it doesn't exist
    - create krb5.conf, kdc.conf, kadm.conf under /etc/krb5
    - create principal database
    - create a user principal for database admin
    - add principals used by kadmin into its keytab
    - start krb5kdc and kadmin service

Examples:

The command below sets up KDC on localhost:

    snake # kdccfg -s

The command below sets up KDC on a remote host:

    snake # kdccfg -s deadduck

The command below sets up KDC on localhost (snake.sfbay), and maps
not only sfbay.sun.com domain, but also central.sfbay.com, prc.sun.com
to ACME.COM realm (the default one).

    snake # kdccfg -s -d central.sfbay.com,prc.sun.com

2) kdc_clientcfg

kdc_clientcfg <-s|-c> <-k kdc> [-p princ] ... [host]
    -s          set up the host as Kerberos client
    -c          clean up the host with previous Kerberos client
                configuration
    -k kdc      KDC server
    -p princ    a principal to be created (if -s is specified)
		or deleted (if -c is specified). princ argument
		has the following format:
	
		   principal_name,attr1=value1,attr2=value2,...

		Currently supported attributes include:

		   password
		      the password for user principal. This
		      attribute is optional. If it is not
		      specified, the principal will be
		      considered as a service principal.
		   enctype
		      the encryption type of the key for the
		      principal in KDB. This attribute is
		      optional. If it is not specified, for
		      each supported encryptiion type, a key
		      will be generated in KDB
	
		If the operation is to delete a principal, all
		attributes associated with that principal are
		ignored and thus no need to specify them.

		There can be multiple -p options.
    host        the host to be set up as KDC client (if -s is
		specified) or to be clean up (if -c is specified)
		This is optional. If no host is specified,
                localhost will be used.

kdc_clientcfg sets up the specified host as Kerberos client, using
a previously configured KDC. If the host isn't specified, localhost
is used.

To set up KDC client, the tool does the following:

    - synchronize system time with KDC
    - create /etc/resolv.conf if it doesn't exist
    - create /etc/krb5.conf
    - create principals user passed with -p options

Note that, although it works, there is no need to run kdc_clientcfg
on a KDC. A KDC is its own client by nature. If you need to create
service principals for the host on which KDC is running, you can use
princadm tool.

Examples:

The commands below set up a remote host (deadduck) as KDC, and creates
a host principal on the remote host. Then it sets up localhost (snake)
as KDC client, and creates a user principal and a host principal on
localhost (snake):

    snake # kdccfg -s deadduck
    snake # princadm -s -p host/deadduck.sfbay.sun.com deadduck
    snake # kdc_clientcfg -s -k deadduck -p test001,password=l1admin \
	    -p host/snake.sfbay.sun.com

The command below calls kdc_clientcfg with -c to clean up the setup
on localhost in above example. Note it uses -p option to remove
principals it created during setup:

    snake # kdc_clientcfg -c -p test001 -p host/snake.sfbay.sun.com


3) krb5nfscfg

krb5nfscfg <-s|-c> [host]
    -s          set up the host for kerberized NFS
    -c          clean up the host with previous kerberized NFS
                configuration
    host        the host to be set up for kerberized NFS (if -s is
		specified) or to be clean up (if -c is specified).
		This is optional. If no host is specified, localhost
	  	will be used.

This tool sets up kerberized NFS on the specified host. If the host
isn't specified, localhost is used.

To set up NFS support for Kerberos, the tool does the following:

    - modify /etc/nfssec.conf
    - make sure rpc/gss service is online
    - create nfs/$fqdn principal, which is needed by nfs service

Examples:

The commands below set up a remote host (deadduck) as KDC, and
localhost (snake) as KDC client, and enable kerberized NFS on both
hosts:

    snake # kdccfg -s deadduck
    snake # kdc_clientcfg -s -k deadduck -p host/snake.sfbay.sun.com
    snake # krb5nfscfg -s deadduck
    snake # krb5nfscfg -s

4) princadm

princadm <-s|-c> <-p princ>... [host]
    -s          create principals specified with -p option(s)
    -c          delete principals specified with -p option(s)
    -p princ    a principal to be created (if -s is specified)
		or deleted (if -c is specified). princ argument
		has the following format:
	
		   principal_name,attr1=value1,attr2=value2,...

		Currently supported attributes include:

		   password
		      the password for user principal. This
		      attribute is optional. If it is not
		      specified, the principal will be
		      considered as a service principal.
		   enctype
		      the encryption type of the key for the
		      principal in KDB. This attribute is
		      optional. If it is not specified, for
		      each supported encryptiion type, a key
		      will be generated in KDB
	
		If the operation is to delete a principal, all
		attributes associated with that principal are
		ignored and thus no need to specify them.

		There can be multiple -p options.
    host        the host for which service principals will be
                created or deleted. If host is not specified,
                localhost will be used.

This tool creates/deletes specified principals in/from krb5 database
and/or keytab. The principals are specified with -p options.

When creating/deleting principals, the tool automatically adds/removes
those principals into/from keytab.

    - When creating a principal, if user doesn't provide password for
      it, the principal will be considered as a service principal.
      Its keys will be generated automatically by krb5, and the tool
      will add them into keytab.

    - When deleting a principal, if there are keys for the the
      principal in keytab, the tool will remove them from keytab.

Because services principals (including host principal) are host specific,
they should only be added into the keytab of the host where those
services are running. The tool checks this by comparing host component
of user passed service principals with FQDN of the target host (either
localhost or the remote host user specified).

Examples:

The command below creates nfs/snake.sfbay.sun.com and test001 principals,
note the usage of password and enctype attributes. Because
nfs/snake.sfbay.sun.com is a service principal, the tool also adds its
keys into keytab on localhost.

    snake # princadm  -s \
	    -p nfs/snake.sfbay.sun.com,enctype=aes128-cts-hmac-sha1-96 \
	    -p test001,password=l1admin,enctype=des-cbc-crc

The command below deletes nfs/snake.sfbay.sun.com and hx156269 principals.
It also removes nfs/snake.sfbay.sun.com from keytab on localhost:

    snake # princadm  -c -p nfs/snake.sfbay.sun.com -p hx156269

The command below creates nfs/deadduck.sfbay.sun.com principal and adds
it into keytab on deadduck host:

    snake # princadm  -s -p nfs/deadduck.sfbay.sun.com deadduck

5) kinfo

kinfo <config | princ | ccache | log | all> [host]
    config	print system configuration information that help
		to debug setup issues. It includes hostname, OS
		version, system time, installed packages, DNS
		setup, and Kerveros configuration information
		like realm, kdc, and the mapped domains.
    princ	print all principals in Kerberos database.
    ccache	print cached tickets saved in credentials cache file.
    log		print the last 10 lines in /var/krb5/kdc.log if
		the host is KDC, and the last 10 lines of
		/var/adm/messages.
    all		print all the above information.

This tool prints information (ie., configuration, existing principals,
cached tickets, error messagesin log files, etc) that helps to debug
issues.

Examples:

The following command prints system configuration which may help to debug
Kerberos issues:

    snake # kinfo config

The following command prints all principals on KDC:

    snake # kinfo princ

The following command prints all contents in credentials cache file:

    snake # kinfo ccache


Prerequisites
=============

Before you use these tools, you need to check the following things:

1) You can use the tools over the network. A copy of these tools is
   available in the STC gate under $GATE/proto/tools/krb5tools, where
   $GATE represents the path to the location of the gate. To use the
   tools, add the bin subdir into your PATH environment variable.
   For example:

      # export PATH=/ws/stcnv-gate/proto/tools/krb5tools/bin:$PATH

   You can also install these tools on your host. For installation
   instructions, see Installation section.

2) You need to be root to run these tools

3) If you want to use these tools to configure a remote host, you
   need to make sure you have rsh or ssh access to that remote
   host as root.

   Notes: rsh is used by default. If you want to use ssh, you need
   to set RSH to "ssh".

   To enable rsh access to the remote host, you need to do the
   following on that remote host:

   - create ~root/.rhosts file on the remote host, which contains a line
     like "+ +"
   - comment out "CONSOLE=/dev/console" line in /etc/default/login
     on that remote host

   To enable ssh access to the remote host, please refer to Appendix
   A for the detailed steps to do that.

4) Customize environment variables if necessary. Below are variables
   used by krb5tools. Among them, the only one you need to check
   is DNS_SERVER. If you want to output more debug information,
   you also need to set KRB5TOOLS_DEBUG. For all the others
   variables, they should just work fine.

    DNS_SERVER      - IP address of your dns server. Default value
                      is 129.145.155.226 (only valid within Sun).
 		      If that doesn't work for your domain, you
		      need to change it.

    KRB5TOOLS_DEBUG - debugging flag. Default value is 0, which
                      means no debug information. See more details
                      in "How to Debug These Tools" section.

    REALM           - kerberos realm. Default value is ACME.COM.

    KDB_PASSWD      - master password for krb5 database, used by
                      kdb5_util(1M). Default value is abc123.

    ADMIN_USER      - krb5 database administration principal, used
                      by kamdin(1M). Default value is test.

    ADMIN_PASSWD    - password for $ADMIN_USER. Default value is
                      abc123.

    TMPDIR          - directory to place temporary files. Default
                      value is /usr/tmp.

    RSH             - remote shell to use. Valid values are "rsh" and
                      "ssh". Default value is "rsh".

5) These tools need to get FQDN for the host they run on or they
   try to set up. So it is recommended that all hosts should have
   reverse DNS lookup. If this can't be satisfied, then user needs
   pass FQDN for the remote host, for example:

      # kdccfg -s cruse.prc.sun.com.

   Note the trailing dot, this is required so that tools can detect
   that a FQDN is passed.

   If the host to be set up is localhost, then just call these tools
   as usual, for example:

      # kdccfg -s

   In this case, the tool will use NIS domainname to try to generate
   a valid FQDN for localhost.


How to Debug
============

By default, all tools print out error messages for diagnosis if
something went wrong. In most cases, these message should be enough
to help users to find the cause for failures.

In some cases, however, if those information is not enough, or if
one needs to debug the tools themselves, one can set KRB5TOOLS_DEBUG
environment variable before running these tools. Currently this
variable can have three values:

   0 - no debugging information. This is the default value.
   1 - print some debugging information. This help to identify what
       went wrong quickly.
   2 - print all debugging information. The output is very verbose.


Installation
============

You can install the tools on your localhost, using the following
steps:

    # pkgadd -d <package location> SUNWstc-krb5tools

The default installation location is /opt/SUNWstc-krb5tools.  To use the
tools from this location, add /opt/SUNWstc-krb5tools/bin to your PATH
environment variable:

    # export PATH=$PATH:/opt/SUNWstc-krb5tools/bin


Building Tools from Source
==========================

The krb5tools package can be built from source.  To do this, place the
the source code in an STC workspace and invoke 'stf_build'.  An example
build recipe:

    # cd <WS_ROOT>/usr/src/tools/krb5tools
    # stf_build package

where <WS_ROOT> represents the root of the STC workspace being built.
'stf_build' is part of the SUNWstc-stf package.  These commands will
create an installable package directory at
	<WS_ROOT>/packages/`uname -p`/SUNWstc-krb5tools
which can be installed as described in the "Installation" section above.


Appendix A: How to Set Up Password-less SSH Access for Root
===========================================================

1) generate RSA authentication keys for root on localhost, keep
   pressing Return key when prompted

	localhost# ssh-keygen -t rsa

   This will generate public key in ~root/.ssh/id_rsa.pub and private
   key in ~root/.ssh/id_rsa.

2) add the root's public key in ~root/.ssh/authorized_keys on the remote
   host

     a) transfer ~root/.ssh/id_rsa.pub on localhost to the remote host.
        Suppose it is saved under /tmp.

     b) add public key contained in that file into ~root/.ssh/authorized_keys

	remotehost#  cat >> ~root/.ssh/authorized_keys < /tmp/id_rsa.pub

     c) make sure ~root/.ssh/authorized_keys file permission is 644.

3) modify /etc/ssh/sshd_config on remote host to allow public key
   authentication for root. The line for PermitRootLogin should be
   like the following:

	remotehost# grep "^PermitRootLogin" /etc/ssh/sshd_config
	PermitRootLogin without-password

4) start ssh-agent on localhost host and call ssh-add to load root's
   private key

      	localhost# [[ -n $SSH_AUTH_SOCK ]] && ssh-agent -k
	localhost# eval `ssh-agent -s`
	localhost# ssh-add
	
   use the following command to verify the key has been loaded
   successfully.

	localhost# ssh-add -l

5) get public key of the remote host and save it into ~root/.ssh/known_hosts
   on localhost. This is done automatically when you connect to
   the remote host via SSH for the first time. Type "yes" and press
   Return key when prompted.

	localhost# ssh dubya
	The authenticity of host 'dubya (10.4.196.208)' can't be established.
	RSA key fingerprint is 09:53:a6:16:6f:1b:49:38:ca:06:63:6e:16:ef:c7:69.
	Are you sure you want to continue connecting (yes/no)? yes
	Warning: Permanently added 'dubya,10.4.196.208' (RSA) to the list of
	known hosts.
	Last login: Thu Mar  8 21:23:44 2007 from assassin
	Sun Microsystems Inc.   SunOS 5.11      snv_59  October 2007
	#

   Note: the host key for remote host may change if it is reinstalled.
   In that event, the one cached in ~root/.ssh/known_hosts on localhost is
   stale and the above ssh command will fail, printing a diagnostic
   message.

   If the diagnostic message indicates that the failure may be related
   to a changed host key, you can remove the line for the remote machine
   from ~root/.ssh/known_hosts and try ssh command again.

6) now everything is done and you should be able to ssh the remote
   host as root.

	localhost# ssh dubya
	Last login: Thu Mar  8 22:34:43 2007 from assassin
	Sun Microsystems Inc.   SunOS 5.11      snv_59  October 2007
	#

Indexes created Sat Nov 28 01:19:25 UTC 2009

Terms of Use | Privacy | Trademarks | Copyright Policy | Site Guidelines | Help
Your use of this web site or any of its content or software indicates your agreement to be bound by these Terms of Use.
Copyright © 1995-2008 Sun Microsystems, Inc.