man-page-license-change-20071225
[openafs.git] / doc / man-pages / pod1 / fs_newalias.pod
1 =head1 NAME
2
3 fs_newalias - Creates a new alias for a cell
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<fs newalias> S<<< [B<-alias>] <I<alias name>> >>>
11     S<<< [B<-name>] <I<cell name>> >>> [B<-help>]
12
13 =for html
14 </div>
15
16 =head1 DESCRIPTION
17
18 The B<fs newalias> command is used when the AFS Cache Manager is in
19 Dynamic Root (B<-dynroot>) mode. It creates a symbolic link in F</afs>
20 from an alias to the full name of the cell. It also creates a symbolic
21 link from the alias prepended with C<.> to the full name of the cell
22 prepended with C<.>, the convention for access to the read/write version
23 of the C<root.cell> volume of that cell.
24
25 This command is used to supplement aliases created via the F<CellAlias>
26 configuration file when B<afsd> starts.
27
28 Traditionally, these aliases would be created by the local AFS
29 administrator by creating symbolic links in the C<root.afs> volume. Such
30 symlinks do not appear when Dynamic Root is enabled because, with Dynamic
31 Root, the Cache Manager does not mount or look at the C<root.afs>
32 volume. This alias capability is a replacement that allows such short
33 names to be created under client control.
34
35 =head1 CAUTIONS
36
37 Aliases created with B<fs newcell> are only temporary and will be lost
38 when the AFS Cache Manager is restarted or the client machine is
39 rebooted. In order to make the alias permanent, it must be put into the
40 F<CellAlias> file.
41
42 There is no way to remove an alias once created without restarting the
43 AFS Cache Manager.
44
45 =head1 OPTIONS
46
47 =over 4
48
49 =item B<-alias> <I<alias name>>
50
51 This is the short name to which the user wants to map the real cell name.
52
53 =item B<-name> <I<cell name>>
54
55 This is the real cell name.
56
57 =item B<-help>
58
59 Prints the online help for this command. All other valid options are
60 ignored.
61
62 =back
63
64 =head1 OUTPUT
65
66 This command has no output.
67
68 =head1 EXAMPLES
69
70 There are two ways to call B<fs newalias>:
71
72    % fs newalias openafs openafs.org
73    % fs newalias -alias openafs -name openafs.org
74
75 Both of the above examples create an alias C<openafs> for the cell
76 C<openafs.org>. Two links wil be created in F</afs>:
77
78    /afs/openafs   ->  /afs/openafs.org
79    /afs/.openafs  ->  /afs/.openafs.org
80
81 =head1 PRIVILEGE REQUIRED
82
83 The issuer must be logged in as the local superuser root.
84
85 =head1 SEE ALSO
86
87 L<afsd(8)>,
88 L<CellAlias(5)>,
89 L<fs_listaliases(1)>
90
91 =head1 COPYRIGHT
92
93 Copyright 2007 Jason Edgecombe <jason@rampaginggeek.com>
94
95 This documentation is covered by the BSD License as written in the
96 doc/LICENSE file. This man page was written by Jason Edgecombe for
97 OpenAFS.