man-page-fs-sysname-improvements-20071128
[openafs.git] / doc / man-pages / pod1 / fs_sysname.pod
1 =head1 NAME
2
3 fs_sysname - Reports or sets the CPU/operating system type
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<fs sysname> S<<< [B<-newsys> <I<new sysname>>]+ >>> [B<-help>]
11
12 B<fs sy> S<<< [B<-n> <I<new sysname>>]+ >>> [B<-h>]
13
14 =for html
15 </div>
16
17 =head1 DESCRIPTION
18
19 The B<fs sysname> command sets or displays the local machine's
20 CPU/operating system type as recorded in kernel memory. The Cache Manager
21 substitutes the string for the I<@sys> variable which can occur in AFS
22 pathnames; the I<OpenAFS Quick Beginnings> and I<OpenAFS Administration
23 Guide> explain how using I<@sys> can simplify cell configuration. It is
24 best to use it sparingly, however, because it can make the effect of
25 changing directories unpredictable.
26
27 The command always applies to the local machine only. If issued on an NFS
28 client machine accessing AFS via the NFS/AFS Translator, the string is set
29 or reported for the NFS client machine. The Cache Manager on the AFS
30 client machine serving as the NFS client's NFS/AFS translator machine
31 stores the value in its kernel memory, and so can provide the NFS client
32 with the proper version of program binaries when the user issues commands
33 for which the pathname to the binaries includes I<@sys>. There is a
34 separate record for each user logged into the NFS client, which implies
35 that if a user adopts a new identity (UNIX UID) during a login session on
36 the NFS client -- perhaps by using the UNIX B<su> command -- he or she
37 must verify that the correct string is set for the new identity also.
38
39 =head1 OPTIONS
40
41 =over 4
42
43 =item B<-newsys> <I<new sysname>>
44
45 Sets the CPU/operating system indicator string for the local machine. This
46 option may be used multiple times in the same invocation, which sets I<@sys>
47 to an array of values. When I<@sys> contains an array of values, the first
48 value that matches a path is used.
49
50 If this argument is omitted, the output displays the current setting
51 instead. AFS uses a standardized set of strings; consult the I<OpenAFS Quick
52 Beginnings> or I<OpenAFS Release Notes>.
53
54 =item B<-help>
55
56 Prints the online help for this command. All other valid options are
57 ignored.
58
59 =back
60
61 =head1 OUTPUT
62
63 When the B<-newsys> argument is omitted, the output reports the machine's
64 system type in the following format:
65
66    Current sysname is '<system_type>'
67
68 When the B<-newsys> argument is included, the output is the following:
69
70    fs: new sysname list set.
71
72 =head1 EXAMPLES
73
74 The following example shows the output produced on a Sun SPARCStation
75 running Solaris 5.7:
76
77    % fs sysname
78    Current sysname is 'sun4x_57'
79
80 The following command defines a machine to be a IBM RS/6000 running AIX
81 4.2:
82
83    % fs sysname -newsys rs_aix42
84
85 The following command defines a machine to be Mac OS X PPC and a
86 custom type 'foo'. The second command queries the new sysname:
87
88    % fs sysname -newsys ppc_darwin_80 -newsys foo
89    fs: new sysname list set.
90    % fs sysname
91    Current sysname list is 'ppc_darwin_80' 'foo'
92
93 If I<@sys> is C<ppc_darwin_80 foo>, then C<cd @sys> will try to change
94 to the C<ppc_darwin_80> directory. If the C<ppc_darwin_80> directory
95 doesn't exist, then the C<foo> directory is tried.
96
97 =head1 PRIVILEGE REQUIRED
98
99 To display the current setting, no privilege is required. To include the
100 B<-newsys> argument on an AFS client machine, the issuer must be logged in
101 as the local superuser C<root>.
102
103 =head1 SEE ALSO
104
105 L<fs_exportafs(1)>,
106 L<sys(1)>
107
108 I<OpenAFS Quick Beginnings>
109 L<http://www.openafs.org/pages/doc/QuickStartUnix/auqbg000.htm>
110
111 I<OpenAFS Administration Guide>
112 L<http://www.openafs.org/pages/doc/AdminGuide/auagd000.htm>
113
114 For the list of assigned standard sysname values, see
115 L<http://grand.central.org/numbers/systypes.html>
116
117 =head1 COPYRIGHT
118
119 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
120
121 This documentation is covered by the IBM Public License Version 1.0.  It was
122 converted from HTML to POD by software written by Chas Williams and Russ
123 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.