[hcoop/debian/openafs.git] / doc / man-pages / pod5 / ThisCell.pod

=head1 NAME

ThisCell - Defines the local cell name

=head1 DESCRIPTION

The F<ThisCell> file defines the local cell name.  There are two versions
of this file, one for a AFS client and one for an AFS server.

=head2 Client ThisCell

The client version of the F<ThisCell> file defines the complete Internet
domain-style name (for example, C<example.com>) of the cell to which the local
client machine belongs. It must reside in the F</usr/vice/etc> directory
on every AFS client machine. To change a client machine's cell membership,
edit the file and reboot the machine.

The file is in ASCII format and contains a character string on a single
line. The I<OpenAFS Quick Start Guide> instructs the administrator to
create it during the installation of each client machine.

The client machine's cell membership determines three defaults important
to its functioning:

=over 4

=item *

The cell in which the machine's users authenticate by default.  The effect
is two-fold:

=over 4

=item *

The AFS-modified login utilities and the klog command interpreter contact
an Authentication Server in the cell named in the F<ThisCell> file (unless
B<-cell> argument to the B<klog> command specifies an alternate cell).

=item *

The command interpreters combine the cell name with the password that the
user provides, generating an encryption key from the combination. For
authentication to succeed, both the cell name and password must match the
ones used to generate the user's encryption key stored in the
Authentication Database.

=back

=item *

The cell the Cache Manager considers its local, or home, cell. By default,
the Cache Manager allows programs that reside in its home cell to run with
setuid permission, but not programs from foreign cells. For more details,
see the B<fs getcellstatus> and B<fs setcell> reference pages.

=item *

Which AFS server processes the local AFS command interpreters contact by
default as they execute commands issued on the machine.

=back

The client version of the F<ThisCell> file is distinct from the server
version, which resides in the F</usr/afs/etc> directory on each AFS server
machine. If a server machine also runs as a client, it is acceptable for
the server and client versions of the file on the same machine to name
different cells. However, the behavior that results from this
configuration can be more confusing than useful.

=head2 Server ThisCell

The server version of the F<ThisCell> file defines the complete Internet
domain-style name (for example, C<example.com>) of the cell to which the
server machine belongs. It must reside in the F</usr/afs/etc> directory on
every AFS server machine.

The file is in ASCII format and contains a character string on a single
line. The initial version of the file is created with the B<bos
setcellname> command during the installation of the cell's first file
server machine, and the I<OpenAFS Quick Start Guide> includes instructions
for copying it over to additional server machine during their
installation.

The only reason to edit the file is as part of changing the cell's name,
which is strongly discouraged because of the large number of configuration
changes involved. In particular, changing the cell name requires
rebuilding the entire Authentication Database, because the Authentication
Server combines the cell name it finds in this file with each user and
server password and converts the combination into an encryption key before
recording it in the Database.

=head1 SEE ALSO

L<bos_setcellname(8)>,
L<fs_getcellstatus(1)>,
L<fs_setcell(1)>

=head1 COPYRIGHT

IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

This documentation is covered by the IBM Public License Version 1.0.  It was
converted from HTML to POD by software written by Chas Williams and Russ
Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
Commit	Line	Data
805e021f CE	1	=head1 NAME
	2
	3	ThisCell - Defines the local cell name
	4
	5	=head1 DESCRIPTION
	6
	7	The F<ThisCell> file defines the local cell name. There are two versions
	8	of this file, one for a AFS client and one for an AFS server.
	9
	10	=head2 Client ThisCell
	11
	12	The client version of the F<ThisCell> file defines the complete Internet
	13	domain-style name (for example, C<example.com>) of the cell to which the local
	14	client machine belongs. It must reside in the F</usr/vice/etc> directory
	15	on every AFS client machine. To change a client machine's cell membership,
	16	edit the file and reboot the machine.
	17
	18	The file is in ASCII format and contains a character string on a single
	19	line. The I<OpenAFS Quick Start Guide> instructs the administrator to
	20	create it during the installation of each client machine.
	21
	22	The client machine's cell membership determines three defaults important
	23	to its functioning:
	24
	25	=over 4
	26
	27	=item *
	28
	29	The cell in which the machine's users authenticate by default. The effect
	30	is two-fold:
	31
	32	=over 4
	33
	34	=item *
	35
	36	The AFS-modified login utilities and the klog command interpreter contact
	37	an Authentication Server in the cell named in the F<ThisCell> file (unless
	38	B<-cell> argument to the B<klog> command specifies an alternate cell).
	39
	40	=item *
	41
	42	The command interpreters combine the cell name with the password that the
	43	user provides, generating an encryption key from the combination. For
	44	authentication to succeed, both the cell name and password must match the
	45	ones used to generate the user's encryption key stored in the
	46	Authentication Database.
	47
	48	=back
	49
	50	=item *
	51
	52	The cell the Cache Manager considers its local, or home, cell. By default,
	53	the Cache Manager allows programs that reside in its home cell to run with
	54	setuid permission, but not programs from foreign cells. For more details,
	55	see the B<fs getcellstatus> and B<fs setcell> reference pages.
	56
	57	=item *
	58
	59	Which AFS server processes the local AFS command interpreters contact by
	60	default as they execute commands issued on the machine.
	61
	62	=back
	63
	64	The client version of the F<ThisCell> file is distinct from the server
65	version, which resides in the F</usr/afs/etc> directory on each AFS server
66	machine. If a server machine also runs as a client, it is acceptable for
67	the server and client versions of the file on the same machine to name
68	different cells. However, the behavior that results from this
69	configuration can be more confusing than useful.
70
71	=head2 Server ThisCell
72
73	The server version of the F<ThisCell> file defines the complete Internet
74	domain-style name (for example, C<example.com>) of the cell to which the
75	server machine belongs. It must reside in the F</usr/afs/etc> directory on
76	every AFS server machine.
77
78	The file is in ASCII format and contains a character string on a single
79	line. The initial version of the file is created with the B<bos
80	setcellname> command during the installation of the cell's first file
81	server machine, and the I<OpenAFS Quick Start Guide> includes instructions
82	for copying it over to additional server machine during their
83	installation.
84
85	The only reason to edit the file is as part of changing the cell's name,
86	which is strongly discouraged because of the large number of configuration
87	changes involved. In particular, changing the cell name requires
88	rebuilding the entire Authentication Database, because the Authentication
89	Server combines the cell name it finds in this file with each user and
90	server password and converts the combination into an encryption key before
91	recording it in the Database.
92
93	=head1 SEE ALSO
94
95	L<bos_setcellname(8)>,
96	L<fs_getcellstatus(1)>,
97	L<fs_setcell(1)>
98
99	=head1 COPYRIGHT
100
101	IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
102
103	This documentation is covered by the IBM Public License Version 1.0. It was
104	converted from HTML to POD by software written by Chas Williams and Russ
105	Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.