source: trunk/third/cns/doc/install.texinfo @ 8789

\input texinfo    @c -*-texinfo-*-

@finalout
@setfilename kerb-inst-man

@ifinfo

@emph{Cygnus Network Security
Installation Notes}
January 1995

John Gilmore
Pat McGregor
Cygnus Support

CNS includes documentation and software developed at the Massachusetts
Institute of Technology, which includes this copyright information:
 
Copyright @copyright{} 1989 by the Massachusetts Institute of Technology. 

@quotation  
Export of software employing encryption from the United States of
America is assumed to require a specific license from the United States
Government.  It is the responsibility of any person or organization
contemplating export to obtain such a license before exporting.
@end quotation

WITHIN THAT CONSTRAINT, permission to use, copy, modify, and distribute
this software and its documentation for any purpose and without fee is
hereby granted, provided that the above copyright notice appear in all
copies and that both that copyright notice and this permission notice
appear in supporting documentation, and that the name of M.I.T. not be
used in advertising or publicity pertaining to distribution of the
software without specific, written prior permission.  M.I.T. makes no
representations about the suitability of this software for any purpose.
It is provided ``as is'' without express or implied warranty.
 
Copyright @copyright{} 1993, 1994, 1995 Cygnus Support.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries a copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).
@end ignore

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.

@end ifinfo

@setchapternewpage odd
@settitle Cygnus Network Security
@titlepage
@title Cygnus Network Security
@subtitle Installation Notes
@sp 2
@subtitle January 1995
@vfill
@author Mark Eichin
@author Pat McGregor
@author Cygnus Support

@page

@vskip 0pt plus 1filll

CNS includes documentation and software developed at the Massachusetts
Institute of Technology, which includes this copyright information:
 
Copyright @copyright{} 1989 by the Massachusetts Institute of Technology. 

@quotation  
Export of software employing encryption from the United States of
America is assumed to require a specific license from the United States
Government.  It is the responsibility of any person or organization
contemplating export to obtain such a license before exporting.
@end quotation

WITHIN THAT CONSTRAINT, permission to use, copy, modify, and distribute
this software and its documentation for any purpose and without fee is
hereby granted, provided that the above copyright notice appear in all
copies and that both that copyright notice and this permission notice
appear in supporting documentation, and that the name of M.I.T. not be
used in advertising or publicity pertaining to distribution of the
software without specific, written prior permission.  M.I.T. makes no
representations about the suitability of this software for any purpose.
It is provided ``as is'' without express or implied warranty.

Copyright @copyright{} 1993, 1994, 1995 Cygnus Support.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.
@end titlepage

@ifinfo
@node Top, Installing CNS, (dir), (dir)
@top Cygnus Network Security

@menu
* Installing CNS::              Installing CNS at Your Site
* Choosing a Realm Name::       Choosing a Kerberos Realm Name
* Installation overview::       CNS Installation Overview
* Installation on any machine:: Installation on any machine
* Configuring the KDC::         Configuring the Key Distribution Center
* Application server configuration::  Configuring an Application Server
* Adding users::                Adding users to the Kerberos database
@end menu
@end ifinfo
            
@node Installing CNS, Choosing a Realm Name, Top, Top
@chapter Installing CNS at Your Site

Cygnus Support developed Cygnus Network Security (CNS) to provide strong
system access security, with minimal impact on users' ease of access.
Using Kerberos Version 4 encryption and client-server technology, CNS
assures that user identities can be checked securely without
transmitting passwords in clear over the Net.  CNS is useful in closing
up several large security holes: eavesdroppers recording login names and
passwords as your users log in from remote locations; and active attacks
based on providing a fake TCP/IP source address (IP address spoofing).

Introducing CNS to an existing site involves more planning and execution
than installing the average software package.  CNS software is required
on both ends of the remote login connections, and remote users must
change their habits.

To install CNS and make it useful, you have to:

@itemize @bullet
@item 
Install and configure the CNS software on the machines at your site.
@item
Set up a CNS Key Distribution Center server machine.
@item 
[Optional] Set up one or more slave servers for reliability.
@item 
Install and configure CNS client software on the machines from which
your remote users log in.
@item 
Add users and their passwords to your CNS server.
@item 
Inform your users about CNS.
@item 
[Optional] Turn off ordinary @code{rlogin}, @code{telnet}, and
@code{rsh} services so that users are @emph{required} to use CNS rather
than potentially exposing their passwords.
@end itemize

This manual covers only basic installation and configuration of the CNS
software.  See the @ref{Top,,Administration Tools,kerbman,Cygnus Network
Security User and Administrator Documentation for CNS Version 1}, manual
for more detailed information.

@node Choosing a Realm Name, Installation overview, Installing CNS, Top
@chapter Choosing a Realm Name

You must chose a Kerberos realm name for your site.  Although your realm
name can be any string, there are certain conventions.  The @sc{CNS}
programs follow these conventions by default, so if you follow them as
well you have to put less information in the @file{krb.conf} and
@file{krb.realms} configuration files (these configuration files are
described below).

@itemize @bullet
@item
Realm names are always upper case strings.
@item
For a host named @samp{xxx.yyy}, the conventional Kerberos realm is
@samp{XXX.YYY}.
@item
For a host named @samp{xxx.yyy.zzz}, the conventional Kerberos realm is
@samp{YYY.ZZZ}.
@item
For a host named @samp{www.xxx.yyy.zzz}, the conventional Kerberos realm
is @samp{XXX.YYY.ZZZ}, and so forth for additional levels in the host
name.
@end itemize

@node Installation overview, Installation on any machine, Choosing a Realm Name, Top
@chapter CNS Installation Overview

A machine running CNS may act in three roles.  A single machine can act
simultaneously in any combination of these three roles:

@itemize @bullet
@item 
Kerberos Key Distribution Center server (providing password checking
service)
@item 
User Client (providing programs to let users login to Kerberized
application servers)
@item 
Application server (providing @code{rlogin}, @code{telnet}, @code{rsh},
and @code{rcp} services for client machines)
@end itemize

To use CNS, you need a main Key Distribution server and, preferably, one
or more backups.  Backups make it possible for your site to function
even if the main server machine is unavailable.

If possible, you should make @file{kerberos.@var{REALM}} be an alias for
your main server machine.  For example, the main server of the realm
CYGNUS.COM is known as @file{kerberos.cygnus.com}.  When the CNS
binaries need to contact a Key Distribution Center server for a
particular realm, they contact the machine named @samp{kerberos} by
default.  The @file{krb.conf} file may be used to override this default,
as well as to name additional backup servers for a realm.  The
@file{krb.conf} file is described below.

You should normally set up all machines at your site as application
servers.  This permits users to log into them directly using the CNS
programs.

You should set up all machines from which your users log in, as CNS
clients.  This normally includes all machines at your site.

The following sections of this manual tell how to set up each CNS role.

@node Installation on any machine, Configuring the KDC, Installation overview, Top
@chapter Installation on any Machine

@menu
* Background::                  Background Information
* Instructions::                Installation Instructions
@end menu

@node Background, Instructions, Installation on any machine, Installation on any machine
@section Background Information

On all platforms, please use the instructions in the following section
to install the binary software and perform the initial configuration.
(If you need to compile the software from source code, see the
@file{README} file in the source code.)

You need to be operating as the @samp{root} user in order to create the
@file{/usr/kerberos} directory, where the CNS package is being
installed.  You also need to be @samp{root} when running various steps
of the configuration procedures.

Your system's security is only as good as the security of your
@samp{root} password.  Please take other precautions to protect your
system security in addition to installing CNS.  CNS cannot protect you
from someone who is able to steal @samp{root} privileges.  CNS also does
not protect you from break-ins caused by bugs in your daemons (e.g.,
@code{fingerd} or @code{sendmail}).  On almost all Unix systems, if
intruders can break in as an ordinary users, they can become root by
exploiting bugs or imperfect configuration files.

CNS installation is partially automated, but you must do some steps by
hand.  Please read through the installation instructions completely
before you begin the installation.  If you find unfamiliar concepts or
words, please consult the glossary in @ref{Glossary,,Administration
Tools,,Cygnus Network Security User and Administrator Documentation for
CNS Version 1}.

@node Instructions, , Background, Installation on any machine
@section Installation Instructions

These installation instructions are for the installation of pre-compiled
binaries.  Be sure you run this as @samp{root}.

These directions install CNS under @file{/usr/kerberos}.  This version
of the software is not easily installed in other places.  However, if
you want to install it elsewhere, you can do so by making a symbolic
link in @file{/usr/kerberos}.  We recommend that for machines that act
as CNS Kerberos Key Distribution Center servers, you place the files on
a local disk.  This prevents failures due to a file server being down or
unreachable.

The entire CNS Kerberos tree can be safely shared among machines of the
same architecture.  @file{/etc/krb-srvtab} is the only machine-dependent
file.

@enumerate
@item If you wish to put the files somewhere other than @file{/usr/kerberos},
create a symbolic link as follows:
@example
ln -s /where/ever/you/want /usr/kerberos
@end example
All the directories in the @file{/where/ever/you/want} path must exist,
with the possible exception of last one, which is automatically created
when you unpack the distribution software.

@item If CNS is not currently installed on this machine, it is
simplest to unpack the tape directly into @file{/usr/kerberos}.  Change
directory to @file{/}.

@item If CNS is already installed on this machine, it is best to
unpack the tape in a directory other than @file{/usr/kerberos}.  The
installation procedure copies the binaries into place safely, without
disturbing any running programs.  Change directory to a directory with
enough room to hold the CNS binaries.  They unpack into the subdirectory
@file{usr/kerberos}.

@item If you are using a FTP'ed distribution, unpack the binaries using
the command @code{uncompress < @var{machine-type}.tar.Z | tar xvf -}.
The source code is available as a separate tar file, which may be
unpacked using the corresponding command @code{uncompress < src.tar.Z |
tar xvf -}.

@item If your distribution is on tape, unpack the tape using the
@code{tar xv} command.  You may have to use @code{tar xvf @var{TAPE}},
where @var{TAPE} is the name of the tape drive you are using.

The source code is stored as a second file on the same tape.  To unpack
the source code, you must skip the first file on the tape, and then
unpack the sources using @code{tar xvf} just as you unpacked the
binaries.  To skip the first file on the tape, on most systems use
@code{mt -f @var{TAPE} fsf}.  On systems such as HP/UX or Irix 4, you
must use @code{mt -t @var{TAPE} fsf} (i.e., use the option @samp{-t}
rather than @samp{-f}).  On SCO or SVR4 systems, use the command
@samp{tape fsf @var{TAPE}}.  Check the man pages for @samp{mt} or
@samp{tape} on your system.

@item Run @code{usr/kerberos/install/configure}.
@itemize @bullet
@item The configure script prompts:
@smallexample
If you've unpacked the tape in @var{DIR}, 
just press @kbd{RETURN};
If you've installed it below some other directory, 
enter it now.
@end smallexample

@noindent
The configure script tries to determine the directory where you have
unpacked the tape.  If the reported directory is correct, just press
@kbd{RETURN}.  Otherwise, enter the name of the directory where you
unpacked the tape.  If you have not unpacked the tape under @file{/},
the script automatically copies the new binaries into
@file{/usr/kerberos} without overwriting the existing binaries.

@item The CNS configuration script automatically fixes the
permissions on the CNS binaries, and it automatically checks that
appropriate entries have been added to the @file{/etc/services} file.
If any errors occur doing these steps, the script exits with an error
message.

@item If the file @file{/usr/kerberos/lib/krb.conf} exists, the
configuration script assumes that CNS was already installed.  It prints
@smallexample
Existing configuration for realm REALM preserved.
To reconfigure it, delete /usr/kerberos/lib/krb.conf 
and re-run configure.
@end smallexample

@item If the file @file{/usr/kerberos/lib/krb.conf} does not exist, CNS
prompts:
@smallexample
Enter name of local realm (for example, CYGNUS.COM):
@end smallexample

@noindent
Enter the name you wish to use for your realm, all in uppercase. For
one-host sites, the realm name is the normally the same as the host name
(in capital letters).  At larger sites, the realm name is usually the
capitalized name of the main Internet domain (e.g.  CYGNUS.COM or
EFF.ORG).  At large sites, there may be several realms (e.g. ENG.SUN.COM
and MKTG.SUN.COM).
@end itemize

@item If you are updating an existing CNS installation on this machine,
you are almost finished.  You should test the new client programs, such as
@code{kinit} and @code{rlogin}, to make sure they continue to work as
expected.  If this is machine is a Key Distribution Center, you should
reboot it to start running the updated CNS server software.  If this
machine is an application server, you should skip to 
@ref{Application server configuration, Configuring an Application Server,
Configuring an Application Server}, to consider turning off non-CNS
access and to turn on the new @code{ftp} and @code{telnet} daemons.

If this is a new CNS installation, you should continue following the
installation instructions.

@item If your realm name is different from your full Internet
hostname with the first component stripped off, you must tell CNS how to
map your hostname to your realm name.  For example, if your hostname is
@file{bogon.company.org}, CNS programs assume that your realm is
@code{COMPANY.ORG} by default.  If you pick any other realm name
(perhaps @code{MKTG.COMPANY.ORG}), you have to edit the file
@file{/usr/kerberos/lib/krb.realms}.  Add two lines to the file to
specify your domain name suffix, a space, and your realm name.  One line
should start with an initial dot, the other should not have it.
Example:
@example
company.org     MKTG.COMPANY.ORG
.company.org    MKTG.COMPANY.ORG
@end example

If you add your domain name to @file{krb.realms}, make sure that all
your local and remote machines running CNS have the same entries in
their local @file{krb.realms} files.

@item When a CNS client program retrieves a ticket for a realm, it
needs to know the hostname of the Key Distribution Center for that
realm.  The default server host name is @file{kerberos.@var{REALM}}.
For example, the server for the realm @file{CYGNUS.COM} is
@file{kerberos.cygnus.com}.  If your users access realms which do not
follow this convention, or if you want to specify more than one Key
Distribution Center for a given realm, you must modify the file
@file{/usr/kerberos/lib/krb.conf}.  If you make changes to
@file{krb.conf}, you must make sure that the versions on all user
clients correspond.

For each CNS Key Distribution Center or backup center, add a line to the file
@file{/usr/kerberos/lib/krb.conf} that contains the realm name, followed
by a space or tab, and the hostname of one of the Key Distribution
Centers for that realm.  If the realm has multiple key distribution
centers, use multiple lines.  On the line that refers to the master
server (which also runs the @code{kadmind} daemon), add the words
``admin server'' to the end of the line.  Example:
@example
MKTG.CORP.ORG kerberos.corp.org admin server
MKTG.CORP.ORG backupserver.corp.org
PODUNK.UNIVERSITY.EDU kerberos.podunk.edu admin server
NEAR.NET kerberos.near.net
@end example

@noindent
In this example, the last line is not actually necessary, because
@file{kerberos.near.net} is the default server for realm
@file{NEAR.NET}.

The first line of the @file{krb.conf} file is special: it specifies the
name of the default realm on this machine.  Do not change it.

@item @emph{If this is the first time you have installed CNS on your systems,
go on to @ref{Configuring the KDC, Configuring the Key Distribution
Center, Configuring the Key Distribution Center}.  If this is not the
first time you have installed CNS, go to the next step.}

@item If this is a client-only installation, test the installation
by running @code{/usr/kerberos/bin/kinit}.  It should prompt you for a
``Kerberos name,'' by which it means your CNS Kerberos user name.  Enter
your user name in the default realm.  You should get a @code{Password:}
prompt.  If you do not, your client programs cannot find a key
distribution center for that realm; recheck your @file{krb.conf} file.
If you are not running Domain Name Service, also check your @file{/etc/hosts}
file.  If you do get the @code{Password:} prompt, enter your password in
this realm.  @code{Kinit} should exit without any error messages, and
@code{klist} should show a single ticket whose Principal is
``krbtgt.REALM@@REALM.''  You can now test the application programs from
@file{/usr/kerberos/bin} (such as @code{rlogin}), or you can just type
@code{kdestroy} to destroy that ticket.

If your users access multiple realms, test each realm in turn, by typing
@code{kinit -r} and @kbd{RETURN}, entering the user name as above, and
then entering the realm name at the @file{Kerberos realm:} prompt.

@end enumerate

If you are only installing CNS client services, your installation is
complete.  Congratulations.  You and your users should add
@code{/usr/kerberos/bin} to the path used to find programs.

@node Configuring the KDC, Application server configuration, Installation on any machine, Top
@chapter Configuring the Key Distribution Center

This section describes how to configure the Key Distribution Center
(KDC) server machine.  You must have at least one KDC in your realm.
You may also set up backup servers; see @ref{Top,,Administration
Tools,kerbman,Cygnus Network Security User and Administrator
Documentation for CNS Version 1}.

@enumerate

@item Log on to the server machine as @samp{root}.

@item Add @file{/usr/kerberos/bin} and @file{/usr/kerberos/etc} to the
working path.

@item Run @code{kdb_init} to create the initial CNS Kerberos
password database.  Enter the realm name, and make up a good master
password.  For effective system security, it is important to choose a
password that cannot easily be guessed or discovered.  This password is
used to encrypt the database on disk, so that it can be safely included
in normal backup procedures; it is not used for any network operation.
You @emph{must not forget} this password.  Example:
@smallexample
sample# kdb_init
Realm name [default  error-default-realm ]: @file{COMPANY.ORG}
You will be prompted for the database Master Password.
It is important that you NOT FORGET this password.

Kerberos master key: @emph{password does not echo}
Verifying, please re-enter Kerberos master key: @emph{reenter password}

@end smallexample

@item Store the master password in @file{/.k} for convenience or unattended
operation.  (If you do not do this, you must type the master password
each time the system reboots.)  Run @code{kstash}, giving it the master
password:
@smallexample
sample# kstash

Kerberos master key: @emph{password does not echo}

Current Kerberos master key version is 1.

Master key entered.
@end smallexample

@item Set up the database entries for the first user---yourself.
Run @code{kdb_edit}, and enter the master key when prompted.  When it
asks for @code{Principal name:}, enter your user name.  At
@code{Instance:}, just press @kbd{RETURN}.  @code{kdb_edit} tells you
that this entry is not found, and ask whether to create it.  Type
@kbd{y}.

When prompted for the initial password for the user (yourself), enter a
short, easy to remember password.  This will be changed in a few
minutes, so keep it simple.  You are prompted to enter it twice.  Press
@kbd{RETURN} for all the other questions.

When @code{kdb_edit} prompts again for @code{Principal name:}, enter
your user name again, but for @code{Instance:}, type @code{admin}.  This
creates an admin instance that you can later use to add new users and
change user passwords.

To exit @code{kdb_edit}, just press @kbd{RETURN} at the @code{Principal
name:} prompt.

Example:

@smallexample
sample# kdb_edit
Opening database...
 
Kerberos master key: @emph{password does not echo}

Current Kerberos master key version is 1.

Master key entered.  Previous or default values are 
in [brackets]
enter @kbd{RETURN} to leave the same, or new value.

Principal name: jis
Instance: 

<Not found>, Create [y] ? y

Principal: jis, Instance: , kdc_key_ver: 1
New Password: @emph{user's password will not echo}
Verifying, please re-enter 
New Password: @emph{user's password will not echo}

Principal's new key version = 1
Expiration date (enter yyyy-mm-dd) [ 1999-12-31 ] ? 
Max ticket lifetime (*5 minutes) [ 255 ] ? 
Attributes [ 0 ] ? 
Edit O.K.
Principal name: jis
Instance: admin

<Not found>, Create [y] ? y

Principal: jis, Instance: admin, kdc_key_ver: 1
New Password: @emph{user's admin password will not echo}
Verifying, please re-enter 
New Password: @emph{user's admin password will not echo}

Principal's new key version = 1
Expiration date (enter yyyy-mm-dd) [ 1999-12-31 ] ? 
Max ticket lifetime (*5 minutes) [ 255 ] ? 
Attributes [ 0 ] ? 
Edit O.K.
Principal name:         @emph{press @kbd{RETURN} to exit}

@end smallexample

@item Run @code{kerberos &} to start the Key Distribution Center
server (the @code{&} runs the server in the background).  You should
see:
@smallexample
sample#  kerberos &
[1] 22630
sample#  Kerberos server starting
        Sleep forever on error
        Log file is /usr/kerberos/database/kerberos.log
Current Kerberos master key version is 1.

Master key entered.

Current Kerberos master key version is 1
Local realm: COMPANY.ORG
@end smallexample

@item Test the Key Distribution Center server.  Run @code{kinit}
with your username as argument (e.g., @code{kinit jis}).  If you get a
password prompt, the network is okay, and everything is configured
properly for this host to find the server.  Type your password (this is
the password you just entered using @code{kdb_edit}).

If you get @samp{send_to_kdc: retry count exceeded}, then @code{kinit}
could not reach the server for some reason.  Make sure that any entry
for your realm in @file{/usr/kerberos/lib/krb.conf} has the right
machine name. If there is no entry, make sure that the server machine
can be reached using the alias @file{kerberos.@var{REALM}}.  Try
contacting the machine using @code{telnet} or @code{ping}.  Also, check
that the @code{Kerberos} process is actually running.

If you get an immediate @samp{kinit: Can't send request (send_to_kdc)}
the most likely cause is that @code{kinit} can't find or read the
@file{krb.conf} file, or can't find any entries for the selected realm
in that file. If there is a delay before the message, it is more likely
that the file was found but there was some problem communicating with
the server.

@emph{Special note for Solaris 2 users:} Solaris 2 includes a partial
installation of kerberos, consisting of @code{kinit} and little
else. Since the Solaris @code{kinit} is in @file{/usr/bin}, it may
appear in your path ahead of the @file{/usr/kerberos/bin} version that
you've just installed, leading to errors similar to those above. While
the Solaris @code{kinit} will work with CNS Kerberos, it looks in
@file{/etc/krb.conf} instead of @file{/usr/kerberos/lib/krb.conf} and
thus won't find the information you'd expect it to. Since users will
normally have @file{/usr/kerberos/bin} near the front of their path in
order to get the CNS Kerberos @code{rlogin}, @code{rsh}, @code{telnet},
and @code{ftp} instead of the regular (non-Kerberos) versions, they will
also get the correct version of @code{kinit} but this can be a source of
difficulty in an initial installation.

@item Authorize yourself to use the @code{kadmin} program to make
administrative changes to the CNS Kerberos database.  Using a text
editor, create four files in @file{/usr/kerberos/database}:
@file{admin_acl.add}, @file{admin_acl.get}, @file{admin_acl.mod}, and
@file{admin_acl.del}.
These files should all have identical contents.  They should each
contain one line---your username, a period, and @code{admin}.  If you
want to set up multiple administrators, you can add additional lines to
these files now or later.  (You also need to add their username and
password to the CNS Kerberos database using @code{kadmin}---as shown
later---or @code{kdb_edit}.)  Example:
@example
sample# cd /usr/kerberos/database
sample# cat >admin_acl.add
jis.admin
^D
sample# cp admin_acl.add admin_acl.get
sample# cp admin_acl.add admin_acl.mod
sample# cp admin_acl.add admin_acl.del
@end example

If sometime later, while running @code{kadmin}, you get the error
message, ``Insufficient access to perform requested operation,'' it
indicates you have successfully contacted the Admin Server, but your
name was not found in the relevant @file{admin_acl} file.  Look in
@file{/usr/kerberos/database/admin_server.syslog} to find the audit
trail of administrative requests failures marked with @samp{WARNING}.

@item Run @code{kadmind -n &} to start the Admin Server, which handles
administrative requests and password changes.
@smallexample
sample# kadmind -n &
KADM Server KADM0.0A initializing
Please do not use 'kill -9' to kill this job, use a
regular kill instead

KADM Server starting in NON-FASCIST mode for the purposes 
for password changing

Current Kerberos master key version is 1.

Master key entered.
@end smallexample

@item Test the Admin Server by using @code{kadmin} to change your
password.  You must either first log in as yourself, or use the
@samp{-u} argument to @code{kadmin} to provide your user ID.
@smallexample
sample# kadmin -u jis
Welcome to the Kerberos Administration Program, version 2
Type @kbd{help} if you need it.
admin:  cpw jis
Admin password: 
     @emph{the admin password you assigned yourself above}
New password for jis: @emph{invent and remember a good one}
Verifying, please re-enter 
      New password for jis: @emph{type the same one}
Password changed for jis.
admin:  quit
Cleaning up and exiting.
sample#
@end smallexample
Be sure that you remember your new password.  If you forget it, you
cannot use the system.

@item Run @code{kdestroy} to destroy the tickets used in testing.

@item Update your @file{/etc/rc} file, or equivalent, so that these two
daemons are run each time the system reboots:
@example
/usr/kerberos/etc/kerberos &
/usr/kerberos/etc/kadmind -n &
@end example

These should be started early in the boot process---after the file
systems are mounted, but before the portmapper starts up.  The admin
daemon uses an unofficial port number which the portmapper may acquire
if portmapper is started first.

If your system initializes using files in a directory like
@file{/etc/rc2.d}, look for the script which starts @code{portmap}, and
make sure that the daemons are started earlier.  This can be done by
starting them earlier in the same script, or by creating a new script
with a lower number.  On the other hand, make sure that the daemons are
not started until the network has been initialized.

@item @emph{Special note for HP/UX startup}: Under HP/UX
the commands mentioned above should be placed in a seperate file, and
that file should be run from the @code{localrc()} function in the
@file{/etc/rc} file. Placing the commands directly in @code{localrc()}
may cause them to be terminated immediately after @file{/etc/rc} finishes.

@item Reboot your system, examine its messages while it boots, and
rerun the tests, to make sure that the daemons both start successfully.
@end enumerate

@node Application server configuration, Adding users, Configuring the KDC, Top
@chapter Configuring an Application Server

To configure a machine to provide @code{rlogin} and @code{rsh} service,
you need to create a secret key for that machine in the CNS database and
on the host itself.

(If you are upgrading from an existing CNS release to this release, you
have already set up your machine's secret key.  Skip down to the step
``Test your CNS services'', and do the rest of the procedure.)

The master database contains entries for all network services that
require CNS Kerberos authentication.  If, for example, you want to offer
@code{rlogin} service from the machine @file{trickster}, you need to
register @file{trickster} in the master database.

CNS does not recognize full domain names.  Therefore, use the first
component of the DNS hostname (e.g., @file{trickster} for
@file{trickster.company.org}).

@enumerate
@c 1
@item From as account for which you created an admin instance,
run @code{kadmin}.  At the prompt, type:
@smallexample
ank rcmd.@var{hostname}
@end smallexample
@noindent
@code{ank} means ``add new key'' and you are telling it to add a service
key for the @code{rcmd} service on machine @var{hostname}.

@smallexample
sample# kadmin
Welcome to the Kerberos Administration Program, version 2
Type @kbd{help} if you need it.
admin:  ank rcmd.trickster
Admin password: 
    @emph{the jis.admin password you created with kdb_edit}
Password for rcmd.trickster: @emph{some short easy password} 
Verifying, please re-enter 
    Password for rcmd.trickster: @emph{Re-enter.} 
rcmd.trickster added to database.
admin:  quit

@end smallexample

@noindent
Note: You use this same process to add any other new users to the
database, except that you use their username as the argument to the
@code{ank} command.  Remind your users to change their CNS passwords
once they have begun to use CNS, so you do not know what their passwords
are.

@c 2
@item On the application server, as root, run @code{ksrvutil add}. This
creates the srvtab file, @file{/etc/krb-srvtab}.

@smallexample
# ksrvutil add
Name: rcmd
Instance: trickster
Realm: COMPANY.ORG @emph{remember to use uppercase here!}
Version number: 1
New principal: rcmd.trickster@@COMPANY.ORG; version 1
Is this correct? (y,n) [y] y
Password: @emph{Give the easy password}
Verifying, please re-enter Password: @emph{do it again}
Key successfully added.
Would you like to add another key? (y,n) [y] n
Old keyfile in /etc/krb-srvtab.old.
@end smallexample

You must give the same password here that you gave to @code{kadmin} in
the @code{ank} (add new key) process.

@c 3
@item Run @code{ksrvutil change}.  This updates the key to a new one, not
known to you, in both the Kerberos database for your realm, and in the
@file{/etc/srvtab}.

Use the following list of troubleshooting suggestions if any problems
arise at this stage:

@itemize @bullet
@c 3.1
@item Clocks not synchronized.  The time on client machines, and all other
machines communicating via CNS, must be within five minutes of each other.
Synchronize all machine time settings.

@item Incorrect name specification.  Be sure that the file
@file{/usr/kerberos/lib/krb.conf} has the correct realm and key server's
hostname.

@c 3.2
@item Password error.  Type @kbd{rm /etc/krb-srvtab} and run
@code{ksrvutil add} again.

@c 3.3
@item Problem with @code{kinit @var{user}}.  If @code{kinit @var{user}} does
not work, debug that first, using the suggestions in the section
@ref{Configuring the KDC,,Configuring the Key Distribution Center}.

@c 3.4
@item Problem with @code{kinit rcmd.@var{hostname}}.  If @code{kinit
rcmd.@var{hostname}} does not work, there could be several explanations.

If @code{kinit} reports @samp{principal unknown}, then go back and run
@code{kadmin} again and correctly enter the item in the database.

If @code{kinit} reports @samp{incorrect password}, then you have given a
different password than you did originally.  If you remember the correct
password, delete @file{/etc/krb-srvtab}, then go back and run
@code{ksrvutil add} again.  If you do not remember the password, change
the one in the database to something you will remember.  To change the
password, run @code{kadmin} again.  Use @code{cpw rcmd.@var{hostname}}
to set the password to something you will remember.  Delete
@file{/etc/krb-srvtab} and run @code{ksrvutil add} again.  Run
@code{ksrvutil change} again too.  This time, it tells you that the
version numbers of the keys do not match, and ask if you want it to fix
this.  Type @kbd{yes}.

@item Problem only with @code{ksrvutil}. If @code{kinit rcmd.@var{hostname}}
works, but @code{ksrvutil change} fails, in particular with the message
``Retry count exceeded (send_to_kdc)'' verify that the realm name is
both uppercase and spelled correctly in the @file{/etc/krb-srvtab} file
using @code{ksrvutil list}. If it isn't, follow the above procedure for
deleting and correcting the file.
@end itemize

@c 4
@item Update @file{/etc/inetd.conf}.  Add these lines to the file and reset
the @code{inetd} daemon.  Unless your system documentation recommends
another procedure, use @code{kill -HUP} to reset the current daemon.

@iftex
@let@nonarrowing=@comment
@end iftex
@smallexample
klogin  stream tcp nowait root /usr/kerberos/etc/klogind klogind
eklogin stream tcp nowait root /usr/kerberos/etc/klogind eklogind
kpop    stream tcp nowait root /usr/kerberos/etc/popper  popper
kshell  stream tcp nowait root /usr/kerberos/etc/kshd    kshd
@end smallexample
@iftex
@let@nonarrowing=@relax
@end iftex

@c 5
@item Test your CNS services.  
(Remember to update your path to place @file{/usr/kerberos/bin} before
@file{/usr/ucb} in your path variable.)

To try @code{rlogin}: on a working client machine (possibly the same
machine): run @code{kinit}, type your name and password, and then run
@code{rlogin @var{app-hostname}}, supplying the hostname you just set up
as an Application Server.  If it works, try @code{rlogin @var{hostname}
-x} to test an encrypted session; you should get a message indicating
that @samp{DES} is being used to protect all traffic.

@c 6
@item If you wish, turn off non-CNS access.  You may want to
restrict access to only those users who login via the CNS programs.  The
Berkeley versions of @samp{rlogin}, @samp{rsh}, and @samp{rcp} rely on
the return address of the incoming TCP connection for authentication, so
they can be subverted by the use of IP source-address spoofing.  Turning
them off increases your security against break-ins.  To do this, look for
lines in @file{/etc/inetd.conf} for the services @samp{shell} and
@samp{login}.  Comment them out by putting a @kbd{#} at the start of the
line.  After editing @file{/etc/inetd.conf}, you must reset the
@code{inetd} daemon as described above.

@c 7
@item If you wish, use the CNS @code{FTP} and/or @code{telnet}
daemons instead of the system supplied daemons.  The CNS versions
support both the traditional password authentication, and Kerberos
authentication.  Look for lines in
@file{/etc/inetd.conf} for the services @code{telnet} and @code{FTP}.
Replace them with lines which look like this:

@iftex
@let@nonarrowing=@comment
@end iftex
@smallexample
ftp    stream tcp nowait root /usr/kerberos/etc/ftpd    ftpd
telnet stream tcp nowait root /usr/kerberos/etc/telnetd telnetd
@end smallexample
@iftex
@let@nonarrowing=@relax
@end iftex

If you wish to restrict @code{FTP} access to people with valid CNS
authentication (and to anonymous users, if your password file admits
them), use the @samp{-a} option.  This rejects FTP accesses which would
normally involve typing a password across the network unencrypted:

@iftex
@let@nonarrowing=@comment
@end iftex
@smallexample
ftp    stream tcp nowait root /usr/kerberos/etc/ftpd    ftpd -a
@end smallexample
@iftex
@let@nonarrowing=@relax
@end iftex

If you wish to restrict @code{telnet} access to people with valid CNS
authentication, use the @samp{-a valid} option.  This rejects
@code{telnet} connections that would normally involve typing a password
across the network unencrypted:

@iftex
@let@nonarrowing=@comment
@end iftex
@smallexample
telnet stream tcp nowait root /usr/kerberos/etc/telnetd 
    telnetd -a valid
@end smallexample
@iftex
@let@nonarrowing=@relax
@end iftex

(The example above should be entered all on one line; it has been broken
into two lines for convenience in reading this manual.)

After editing @file{/etc/inetd.conf}, you must reset the @code{inetd}
daemon as described above.
@end enumerate

@node Adding users,  , Application server configuration, Top
@chapter Adding Users to the Kerberos Database

Before users can use CNS, they must be added to the Kerberos database.

Users are added with the @code{kadmin} program.

@enumerate

@item Log in as the user for whom you created an admin instance when
you configured the Kerberos database (@pxref{Configuring the
KDC,,Configuring the Key Distribution Center}).

@item Run @code{/usr/kerberos/bin/kadmin}.

@item At the prompt, type @kbd{ank @var{USER}}.  When prompted, enter
your admin password, and then enter a password for the user.
@smallexample
% kadmin
Welcome to the Kerberos Administration Program, version 2
Type @kbd{help} if you need it.
admin:  ank @var{USER}
Admin password: 
    @emph{the admin password you created with kdb_edit}
Password for @var{USER}: @emph{a password} 
Verifying, please re-enter 
    Password for @var{USER}: @emph{Re-enter.} 
@var{USER} added to database.
admin:  quit
%
@end smallexample

@item The user may now run @code{kinit}, giving the password you entered
above.  Encourage the user to use @code{kpasswd} to select a personal
password which you do not know.  If necessary, you can use the
@code{cpw} command in @code{kadmin} to change the user's password to a
known string.
@end enumerate

@contents
@c second page break makes sure right-left page alignment works right
@c with a one-page toc, even though we don't have setchapternewpage odd.
@c end of texinfo file
@bye