.\" $Id: attach.1,v 1.8 91/08/15 16:36:37 lwvanels Exp $ .\" .TH ATTACH 1 "1 July 1991" .ds ]W MIT Project Athena .SH NAME attach \- attach a remote file system to your workstation .SH SYNOPSIS .nf attach [ [ options ] \fIfilesystem\fP ... ] ... attach -l \fIfilesystem\fP ... attach .fi .SH DESCRIPTION \fIAttach\fP is a filesystem-independent utility which allows you attach a filesystem to a directory hierarchy on your workstation. The following filesystems are currently supported: NFS (Network File Protocol), RVD (Remote Virtual Disk), UFS (Unix file system), and AFS (Andrew File System). Attach looks up \fIfilesystem\fP in attach.conf(5) or by using Hesiod(3) to retrieve the file system type, the server host, the name by which the file system is known to the server (e.g., an RVD locker name or NFS server mountpoint), and the default mount point and mode (read-only, read-write). The user may also explicitly specify this information, as described below under the -explicit option. Using the various options specified below, it is possible to supercede the default mount point and mode. In addition, the user can specify that a filesystem be nosuid, so that the operating system will not honor setuid or setgid permissions on the foreign filesystem. The system maintainer may also forcibly set a filesystem so that it will be mounted nosuid by including an entry in the attach.conf file. \fIAttach\fP will attempt to automatically create a NFS mapping using Kerberos (see \fIKerberosintro(1)\fP) for NFS filesystems so that the user will have his normal (authenticated) access to the filesystem. \fIAttach\fP will automatically run the program \fIaklog\fP for AFS filesystems, to authenticate the user with the AFS subsystem. In the case of RVD packs, it is possible to supply an RVD password if Kerberos authentication is not implemented for the RVD subsystem on the workstation and the server. If a password is required and standard input is the controlling terminal, \fIattach\fP prompts for a password. If standard input is not a terminal, \fIattach\fP will not prompt for a password, and will exit with an error status. The default mode is 'w' (read-write). Also supported are 'r' (read-only), 'n' (read-only, do not attempt to authenticate), and 'm' (read-write, attempt to authenticate, but authentication failure is not a fatal error). .PP The following arguments to \fIattach\fP modify its behavior. Default options are marked as such. Unless otherwise marked, all arguments are processed \fIin order\fP. Thus, if a -v option is followed by a -q option, the -q option will take precedence. The long and short forms of each option function identically. If no arguments are given to \fIattach\fP, a list of the currently attached filesystems will be presented. .IP "-verbose or -v" Display verbose information about a mounted filesystem, such as the NFS or RVD server and the server's filesystem name, if the attach is successful. This is the default. Use of this option automatically supresses the -printpath option. .IP "-quiet or -q" Don't display verbose information. Error messages will still be printed. .IP "-force or -f" Ordinarily, \fIattach\fP will not attempt to attach a filesystem which it believes is already attached (as indicated by its appearance in the \fIattachtab(5)\fP file), or which it thinks is being attached or detached by another process. This flag overrides this behavior and \fIforces\fP the filesystem to be attached. This option can be dangerous if used indiscriminately since a filesystem could get attached more than once. .IP "-printpath or -p" \fIAttach\fP normally prints a status message on its standard output indicating the success or failure of the attach operation. This flag causes the pathname of the mounted filesystem to be printed instead. This allows an alias which invokes the \fIattach\fP command to source a C shell command file relative to this pathname, which presumably can set up execution paths and other environment variables appropriate for the use of this filesystem. Use of this option automatically surpresses the -verbose option. .IP "-lookup or -l" This option causes \fIattach\fP to lookup the filesystem definition using either attach.conf(5) or Hesiod(3) and print out the definition, but not to actually attach the filesystem. .IP "-debug or -d" Print debugging information. This will not normally be useful to users. .IP "-map or -y" Attempt to authenticate the user with Kerberos to the filesystem server. The authentication may be necessary in order to have the proper access to the filesystem. This is the default. If the authentication fails and the filesystem is being mounted read-only, a warning is printed and the attach continues. .IP "-nomap or -n" Do not attempt to authenticate the user to the filesystem server. This implicitly invokes the -noremap options. .IP "-remap or -g" Go ahead and remap the user even if the filesystem is already attached. This is the default. .IP "-noremap or -a" Don't remap the user if the filesystem is already attached. .IP "-zephyr or -z" Subscribe to \fIZephyr\fP messages about the server host. This is the default. .IP "-nozephyr or -h" Don't subscribe to \fIZephyr\fP messages about the server host. .IP "-readonly or -r, -write or -w" Overrides the default access mode for the next filesystem. "-r" indicates read-only access, and "-w" indicates write access. .IP "-mountpoint \fImount-point\fP or -m \fImount-point\fP" Overrides the default mount point for the next filesystem. The \fImount-point\fP must be an absolute pathname. .IP "-noexplicit or -x" Tell \fIattach\fP to interpret the \fIfilesystem\fP as a Hesiod name. This if the default. .IP "-explicit or -e" Change the behavior of \fIattach\fP such that the \fIfilesystem\fP is now interpreted as \fIhost:directory\fP (in the case of NFS) or \fIhost:pack\fP (in the case of RVD) instead of as a Hesiod name. This allows arbitrary directories to be attached. When this option is used, the default mount point is \fI/host/directory\fP for NFS filesystems (\fI/host/root\fP for host:/), and \fI/host/pack\fP for RVDs. This can still be overridden by the -m option. .IP "-type \fIfilesystem-type\fP or -t \fIfilesystem-type\fP" Used with the -explicit option to tell \fIattach\fP the type of the filesystem that's going to be attached. It defaults to NFS. .IP "-mountoptions \fIoptions\fP or \-o \fIoptions\fP" Specify options for the mounting of the filesystem. The options are the same as the ones used by \fImount(8)\fP. .IP "-nosetuid or -nosuid or -N" With this option, \fIattach\fP will mount the filesystem with the nosuid option. This causes the kernel not to honor setuid or setgid permission in the filesystem. (Note: this option does not have any effect with AFS filesystems.) .IP "-setuid -suid or -S" This option can be used by a trusted user to forcibly mount a filesystem without the nosuid option. This can be used to override the fact that the system administrator has made an entry such that the filesystem would normally be mounted nosuid. .IP "-override or -O" \fIAttach\fP can be set up so that normal users cannot attach certain filsystems. A trusted user can use this option to override these restrictions. See attach.conf(5) for more information. .IP "-skipfsck or -F" This option indicates that the \fIfsck\fP command should not be run. \fIfsck\fP is normally run on RVD filesystems that are mounted read-write (exclusive) mode. .IP "-lock or -L" This option tells \fIattach\fP to lock the filesystem so that it cannot be unmounted except explicitly by one of the trusted users. This command requires the user to be in the trusted users list. .IP "-user \fIusername\fP or -U \fIusername\fP" This option allows a trusted user to perform an \fIattach\fP command on behalf of another person. The entries added to the \fIattachtab\fP file will indicate that the \fIattach\fP command was run by the specified \fIusername\fP. .IP "-host \fIhostnames\fP or -H \fIhostnames\fP" This option causes \fIattach\fP to list all filesystems that are mounted from the given \fIhostnames\fP. After this option appears on the command line, no more filesystems may be attached; only hostnames may be specified. .PP If the default mount-point for a filesystem (or the mount-point specified with the -m option) does not exist, it is created. Any directories in the path that do not exist are also created. If a directory can't be created, the attach fails. When the filesystem is detached, any directories that were created during the attach are deleted, if possible. The -all option to \fIdetach\fP causes filesystems to be detached in reverse order so that directories can be deleted properly. The first thing \fIattach\fP and \fIdetach\fP do is to attempt to read in /etc/athena/attach.conf, which can be used by the system administrator to customize the behavior of \fIattach\fP and \fIdetach\fP. See \fIattach.conf(5)\fP for more information. If an NFS attach is successful, a mapping for the user is established to the NFS server (under the restraints of the -y, -n, and -g options above). If this mapping fails on a read/write attach, the operation aborts and the filesystem is not attached. If the mapping fails on a read-only attach, a warning is printed but the filesystem is mounted anyway. When an attach is successful and the -nozephyr option is not specified, a \fIZephyr(1)\fP subscription is made for the user for filesystem status message for the appropriate server. These subscriptions are removed when the filesystem is detached. .SH EXAMPLES .nf attach -r -q -m /mymount/X11 x11 -w gnu .fi Attach the filesystem \fIx11\fP to the mountpoint /mymount/X11 in read-only mode. Then attach the filesystem \fIgnu\fP to its default mount point in write mode. Don't print success messages for either mount. .SH DIAGNOSTICS If \fIattach\fP is executed with only a single filesystem argument, the exit status will be one of the following: .TP 5 0 No error encountered. .TP 5 1 Bad arguments. .TP 5 2 Generic error not included in any more specific code. .TP 5 3 Internal fatal error. .TP 5 10 Keberos failure. .TP 5 11 Host communication failure. .TP 5 12 Authentication failure. .TP 5 13 No reserved ports available. .TP 5 20 Bad filesystem name. .TP 5 21 Filesystem already in use by another \fIattach\fP process. .TP 5 22 RVD spinup needs a password and standard input is not a tty. .TP 5 23 FSCK returned an error while validating an RVD spunup in exclusive mode. .TP 5 24 User is not allowed to attach filesystem. .TP 5 25 User is not allowed to attach a filesystem at this mountpoint. .TP 5 26 The remote filesystem does not exist. .PP If more than one filesystem argument is specified, the exit status can be either 0, 1, or 3 as listed above, or: .TP 5 2 Something went wrong with one of the filesystems. .PP If an error is encountered while manipulating one filesystem in the list, \fIattach\fP continues with the other filesystems and returns the exit status 2 after attempting to attach all the other filesystems. .SH NOTE The programs \fIattach(1)\fP, \fIdetach(1)\fP, \fInfsid(1)\fP, and \fIzinit(8)\fP are all really the same program. Typically \fIdetach(1)\fP, \fInfsid(1)\fP and \fIzinit(8)\fP are links to \fIattach\fP. Argv[0] is used to determine which one of the four programs are run. This may be overridden by specifying -P \fIprogname\fP, where \fIprogname\fP should be one of the above four program names. .SH FILES /usr/tmp/attachtab .br /tmp/attach.\fIfilesystem\fP .SH "SEE ALSO" detach(1), nfsid(1), zinit(1), zephyr(1), hesiod(3) .br `Hesiod - Project Athena Technical Plan -- Name Service' .br `Hesiod Applications Programmers' Guide' .br `Hesiod Operations and Maintenance Guide' .SH AUTHORS Robert French, Project Athena .br Theodore Ts'o, Project Athena .br John Carr, Project Athena .br Richard Basch, Project Athena .br Copyright 1988, 1990 Massachusetts Institute of Technology .SH BUGS Nosetuid is not possible for AFS filesystems. Except for 'n', modes are ignored for AFS filesystems. These are side effects of the current implementation using symbolic links. \fIAttach -p\fP with filesystems of type \fIMUL\fP will print out a newline-separated list of all the directories on which filesystems were attached. If used in conjunction with the standard \fIadd\fP and \fIsetup\fP aliases, errors will occur. It is yet undetermined as to what \fIattach -p\fP should output when used on filesystems of type \fIMUL\fP. AIX does not support nosetuid, so attach ignores the nosetuid option on this system. Mount options in attach.conf always override those on the command line.