.\" $Id: installus.man,v 2.14 2012/09/05 23:15:56 ksb Exp $
.\" by Ben Jackson
.\" $Compile: Display%h
.\" $Display: ${groff:-groff} -Tascii -man %f | ${PAGER:-less}
.\" $Install: %b -mDeinstall %o %f && cp %f $DESTDIR/usr/local/man/man1/installus.1
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]1/installus.1*
.TH INSTALLUS 1 LOCAL
.SH NAME
installus - install user supported software
.SH SYNOPSIS
.ds PN "installus
\fI\*(PN\fP [\fB\-1\fP\fBD\fP\fBl\fP\fBn\fP\fBq\fP\fBs\fP\fBv\fP] \fIfiles\fP \fIdestination\fP
.br
\fI\*(PN\fP \fB\-W\fP [\fIfiles\fP]
.br
\fI\*(PN\fP \fB\-L\fP [\fB\-x\fP] [\fIuser\fP] [\fIdirs\fP]
.br
\fI\*(PN\fP \fB\-d\fP [\fB\-r\fP | \fB\-R\fP] [\fB\-n\fP\fBq\fP\fBr\fP\fBv\fP] \fIdestination\fP
.br
\fI\*(PN\fP \fB\-h\fP
.br
\fI\*(PN\fP \fB\-V\fP
.br

.SH DESCRIPTION
Allows non-superusers to maintain software in system binary directories.
See \fBowners\fP(5l) for details on access control.

.PP
From time to time the System Admin may wish to delegate installation
and maintenance of a program to a normal user.  The obvious method of
making a system directory writable by the login's group suffers from
several security exploits.

.PP
Most of these issues can be addressed by making the person who is using the
account type a \fBpassword\fP before they are allowed to update the
installed file.  This makes it much harder for a Bad Guy to trick the
maintainer into (unwittingly) installing a bad version of the program.

.PP
It also makes it possible to install a file into a directory the
maintainer cannot even read.

.PP
To make this as safe as possible (it is never 100% safe) the program
enforces the modes that the target file gets, and logs every install.

.PP
The setuid and setgid bits on the owners control file are part of
the configuration of the directory, see \fBowners\fP(5l).

.SH OPTIONS
.TP
.nf
\fB\-1\fP
.fi
Keep exactly one backup of the installed file.
.TP
.nf
\fB\-d\fP
.fi
Install (make or update) a directory, see \fB\-r\fP.
.TP
.nf
\fB\-D\fP
.fi
Make no backup of target file.
.TP
.nf
\fB\-h\fP
.fi
Print a help message.
.TP
.nf
\fB\-l\fP
.fi
Run \fBranlib\fP(1) on \fIfiles\fP (for libraries) as they're being installed..
.TP
.nf
\fB\-L\fP
.fi
List the files that \fIuser\fP owns.  If the \fIuser\fP is given as
\fIuser\fP\fB:\fP\fIgroup\fP then both are used to check the permissions.
Either of these may be given as \fB*\fP to indicate an unspecified target.
.TP
.nf
\fB\-n\fP
.fi
Tell \fBinstall\fP to trace execution but not modify the filesystem.
.TP
.nf
\fB\-q\fP
.fi
If \fBinstallus\fP (and \fBinstall\fP) can recover from any errors be quiet.
.TP
.nf
\fB\-r\fP
.fi
Build all intervening directories, as necessary.
.TP
.nf
\fB\-R\fP
.fi
Remove the given target.
.TP
.nf
\fB\-s\fP
.fi
Run \fBstrip\fP(1) on \fIfiles\fP as they're being installed.
.TP
.nf
\fB\-v\fP
.fi
Run in verbose mode, and tell \fBinstall\fP to do the same.
.TP
.nf
\fB\-V\fP
.fi
Show version information.
.TP
.nf
\fB\-W\fP
.fi
Show who owns \fIfiles\fP.  Use the getopt spacer double dash (\-\-) to
skip the \fIuser\fP parameter if you are looking at yourself.
.TP
.nf
\fB\-x\fP
.fi
List the programs that ONLY \fIuser\fP owns.

.SH EXAMPLES
.TP
.nf
\fI\*(PN\fP \-sv calls /usr/unsup/bin/calls
.fi
A typical use of \fI\fI\*(PN\fP\fP to update a binary in
/usr/unsup/bin.  This is usually driven from a \fBmake\fP(1) recipe.

.TP
.nf
\fI\*(PN\fP \-W /usr/unsup/bin/prog
.fi
Use \fB\-W\fP option to find the maintainer for a user supported program.

.TP
.nf
\fI\*(PN\fP \-L \-\- \-\- /usr/unsup/bin
.fi
List the files in /usr/unsup/bin you control.

.TP
.nf
\fI\*(PN\fP \-ds /usr/unsup/lib/syzygy
.fi
Create (or update the modes of) a local library directory.

.SH BUGS
The exact semantics of locating and using .owners files has changed since
the \fB\-W\fP and \fB\-L\fP options were written, and their behavior is
probably not ideal.  For example the .owners file path is presented
to the Customer as if it were relative to the target directory (which
it is internally).

.PP
The \fB\-W\fP option excludes the \fB\-d\fP options, to ask who the
owner of a directory is one must append a slash on the name.

.SH CAVEATS
This is a modified version of the the original Purdue University
Computing Center source.  It has been updated to work on more platforms
and has a few more features. \-\- ksb

.SH AUTHOR
Ben Jackson & Kevin Braunsdorf
.br
ben@ben.com & console at-hate-spam ksb.npcguild.org
.br
NPC Guild UNIX Support

.SH "SEE ALSO"
.hlm 0
install(1l), owners(5l), vinst(1l), make(1)