source: trunk/athena/bin/attach/attach.1 @ 5489

.\" $Id: attach.1,v 1.8 1991-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.