.\" $Id: stampctl.man,v 1.12 2012/10/29 17:41:46 ksb Exp $
.\" by KS Braunsdorf
.\" $Compile: Display%h
.\" $Display: ${groff:-groff} -Tascii -man %f |${PAGER:-less}
.\" $Display(*): ${groff:-groff} -T%s -man %f
.\" $Install: %b -mDeinstall -D DESTDIR=${DESTDIR} %o %f && cp %f ${DESTDIR}/usr/local/man/man8/stampctl.8
.\" $Deinstall: ${rm-rm} -f ${DESTDIR}/usr/local/man/man8/stampctl.8*
.TH STAMPCTL 8 LOCAL
.SH NAME
stampctl - control the op authorization stamp facility
.SH SYNOPSIS
.ds PN "stampctl
\fI\*(PN\fP [\fB\-g\fP\~\fIgroup\fP] [\fB\-m\fP\~\fImode\fP] [\fB\-u\fP\~\fIuser\fP] [\fIfacilities\fP]
.br
\fI\*(PN\fP \fB\-M\fP\~\fIstamp\fP [\fB\-n\fP] [\-\fImax\fP] [\fB\-D\fP\~\fIdrop\fP] [\fB\-E\fP\~\fIend\fP] [\fB\-g\fP\~\fIgroup\fP] [\fB\-I\fP\~\fIidle\fP] [\fB\-m\fP\~\fImode\fP] [\fB\-u\fP\~\fIuser\fP] [\fIname[=value\fP]s]
.br
\fI\*(PN\fP \fB\-M\fP\~\fIstamp\fP \fB\-R\fP\~\fIroap\fP [\fB\-nX\fP] [\-\fImax\fP] [\fB\-D\fP\~\fIdrop\fP] [\fB\-E\fP\~\fIend\fP] [\fB\-g\fP\~\fIgroup\fP] [\fB\-I\fP\~\fIidle\fP] [\fB\-m\fP\~\fImode\fP] [\fB\-p\fP \fIservice\fP] [\fB\-T\fP \fItimeout\fP] [\fB\-u\fP\~\fIuser\fP] [\fIname[=value\fP]s]
.br
\fI\*(PN\fP \fB\-k\fP|\fBK\fP|\fBN\fP [\fIstamps\fP]
.br
\fI\*(PN\fP \fB\-v\fP [\fIstamps\fP]
.br
\fI\*(PN\fP \fB\-h\fP
.br
\fI\*(PN\fP \fB\-V\fP
.br
\fI\*(PN\fP \fB\-Q\fP \fIstamp\fP [\fB\-F\fP] [\fItableaus\fP]

.SH DESCRIPTION
A stamp represents the authorization status of a person (group of people)
as a process listening on a local domain socket.
The process holds some facts about the grant in a tableau of name-value
pair, very much like a process's environment.
\fIStampctl\fP manages local authorization stamps by creating, revoking,
refreshing, and deleting these processes.

.P
Mortal users may be allowed to create authorization stamps directly,
with an \fBop\fP rule, or via any other escalated process.  It is a
local site policy issue to decide who can provide authorization to whom:
this program uses file permissions alone to allow or disallow access
to a stamp socket.  For just that reason the program is usually run
escalated to the superuser, or to a dedicated mortal login (viz. "stamp",
aka Phil Atelies, in group "frankage").

.P
The owner of the stamp socket does not have to match the owner of the
manager process.  The stamp process drops to the \fIdrop\fP login after
creating the socket, which could be the real uid of the process, or
the any uid when either the effective (or real) uid is the superuser.

.P
Once created, the stamp is only mutable in two directions: the stamp
may be put in penalty mode, or it may be terminated.  Once put in
penalty mode it denies \fBall\fP authorization requests until it expires.
To terminate the penalty mode a signal must be sent to the process
(see \fB\-K\fP).  The \fB\-n\fP option starts a stamp in penalty mode.

.P
A stamp (stamp directory) may be replaced by a text file to deny all access.
Said file should contain a message to be displayed to
anyone requesting authorization from that stamp.
This is used to lock-out frozen accounts, or at system boot to
prevent the auto-startup of applications and \fBcron\fP tasks, or to
remove access by group, application, or service.

.P
A stamp may be created with advise from a remote authorization service,
under the \fB\-R\fP option.  This remote service is usually an instance
of \fBroapmux\fP(7l), which runs under the \fBtcmpmux\fP(8) service.
Any authorization advise from the remote sevice is loaded before the
requested tableau (see \fB\-X\fP below).

.SH OPTIONS
.TP
.nf
\fB\-\fP\fImax\fP
.fi
Set the maximum number of authorizations allowed by the new stamp created
under \fB\-M\fP.  When the count is exhausted, the stamp terminates.
Any number less than 1 rejects exactly 1 request, then exits.
.TP
.nf
\fB\-D\fP \fIdrop\fP
.fi
Call \fBsetuid\fP(2) to drop to
the specified \fIuser\fP (or \fIuser\fP:\fIgroup\fP)
to process requests.  The prevents the Customer from sending any signals
to the stamp process (or allows it if you like).
.TP
.nf
\fB\-E\fP \fIend\fP
.fi
Specify a maximum time limit in scaled seconds (default "0", no timeout).
This uses the standard simple suffix table from \fPmkcmd\fP's
\fIseconds\fP module.  To be more like \fBsudo\fP specify \fB1h\fP.
.TP
.nf
\fB\-F\fP
.fi
Under \fB\-Q\fP output the requested \fItableaus\fP in the format \fBop\fP
requires for external input of environment variables.  This allows a
jacket to inject stamp data into an escalated process's environment.
.TP
.nf
\fB\-g\fP \fIgroup\fP
.fi
Group ownership for the new stamp.
.TP
.nf
\fB\-H\fP
.fi
Explain the environment interface avaliable.  Since the \fBop\fP
configuration sets environment vairables to pass preferences to
many programs, this is a common options to most jackets.
.TP
.nf
\fB\-h\fP
.fi
Print a brief help message.
.TP
.nf
\fB\-I\fP \fIidle\fP
.fi
Specify an idle timeout in scaled seconds (default "1h", 1 hour).
To be more like \fBsudo\fP specify to \fB10m\fP.
.TP
.nf
\fB\-k\fP | \fB\-K\fP \fIstamps\fP
.fi
Terminate an existing authorization provided by \fIstamps\fP, unless
these stamps are in penalty mode.  The lowercase (\fBk\fP) version
asks the stamp to exit, which fails when the stamp is in penalty mode,
the uppercase version signals the stamp, which fails when the
process has no rights to send the signal.
.TP
\fB\-m\fP \fImode\fP
Permissions for the new stamp or facilities directory.
The default for a stamp socket it to copy the read and
write bits from the enclosing directory.  The default for a directory
is to copy the modes from the enclosing directory.  The mode may
be in symbolic or octal format, any may include a slash (\fB/\fP)
followed by optional bits, see \fBinstall.cf\fP(5l).
.TP
.nf
\fB\-M\fP \fIstamp\fP
.fi
Make an authorization for named \fIstamp\fP.
The tableau of \fIname\fP=\fIvalue\fP pairs specified after
the options may be used as environment variables by escalated process, or
as credentials for future helmet/jacket verification.  See \fBstamp\fP(7l).
If the equal sign and the \fIvalue\fP are omitted, then the value is
recovered from the current environment.
In that case, and when the \fIname\fP is not set in
the environment, the tableau entry is discarded such that it would
appear that the entry was never specified.
.TP
.nf
\fB\-n\fP
.fi
Start in penalty mode (never allow any escalations).
This locks-out the given stamp for a specific time
(set with \fB\-I\fP or \fB\-E\fP).
Force the stamp to penalty mode.  This might be used at the end of change
to prevent further escalations, but killing the stamp has the same effect.
.TP
.fi
\fB\-p\fP \fIservice\fP
.nf
Connect to the tcpmux on the listed \fIservice\fP.  By default \fI\*(PN\fP
connects to the service \*(lqtcpmux\*(rq.
.TP
.fi
\fB\-R\fP \fIroap\fP[:\fImux\fP]
.nf
Request the tcpmux service \fImux\fP from the host \fIroap\fP, rather
than the default \fBroap\fP:\fBroapmux\fP.  This service may redirect
the client with a reply of \fB@\fP\fInew-host\fP:Inew-port\fP.  This is
an extension to RFC1918 that is used to redirect clients as services
migrate.
.TP
.fi
\fB\-T\fP \fItimeout\fP
.nf
Under \fB\-R\fP limit the connection to the \fIroap\fP service to
\fItimeout\fP seconds.  This prevents slow authorization services
from blocking stamp creation for a very long time.
.TP
.fi
\fB\-u\fP \fIuser\fP
.nf
Owner of the new stamp.  The owner does \fBnot\fP have to be the
Customer, in fact that's usually a bad idea.
.TP
.nf
\fB\-v\fP
.fi
Reset the idle timeout for an existing authorization.  This is for compatibility
with \fBsudo\fP, every access to the stamp resets the idle timer as well.
.TP
.nf
\fB\-V\fP
.fi
Show version information.
.TP
.nf
\fB\-Q\fP \fIstamp\fP
.fi
Query the specified \fIstamp\fP for each \fItableau\fP value.  If
all tableau entries exist output them to \fIstdout\fP, else report
the failed entry on \fIstderr\fP and exit non-zero.
.TP
.nf
\fB\-X\fP
.fi
A remote tableau entry under \fB\-R\fP usaully overrides any suggested
local value.  Under this switch the local tableau entry takes precedence.

.SH EXAMPLES
.TP
.nf
\fI\*(PN\fP \-V
.fi
Learn the version, default facility name (usually \*(lqstamp\*(rq), and
default cache directory.
.TP
.nf
\fI\*(PN\fP \-m 1777 \-u phil \-g frankage .
.fi
Build the default directory with liberal modes.  Anyone may
create a stamp in the default directory.  Without an escalation rule
to consult those stamps they are pretty useless.
The \fBphil\fP and  \fBfrankage\fP names are local site policy.
Avoid using "nobody" or "vanilla" as they get over-used all the time.
.TP
.nf
STAMP_FACILITY=. \fI\*(PN\fP \-m 750 \-g wheel . admin
.fi
build the top-level stamp directory, and one for the admin group.
This is usually used at system boot to setup the default modes for
application directories.
.TP
.nf
STAMP_FACILITY=cat \fI\*(PN\fP \-m750/025 \-gcat tiger puma lion jaguar
.fi
Build 4 facility directories with optional modes under the "cat" topic.
.TP
.nf
\fI\*(PN\fP \-M $USER TERM="$TERM" TERMCAP="$TERMCAP" TTT=`tty` ; export STAMP_SPEC="$USER"
.fi
Build a test stamp with 3 tableau entries.
.TP
.nf
/usr/local/libexec/jacket/stamp \-\- true /bin/true 0:0 auth:any ; echo $?
.fi
Test the stamp just created, just as \fBop\fP would.
If this outputs 0 (success) then \fBop\fP would treat this authorization
as valid (when asked).
.TP
.nf
export STAMP_SPEC="$USER:TTY!`tty`"
.fi
Change the requested authorization to deny the current tty session. Try
the previous example again and it should fail (with 77) and the message
"Sorry".
.TP
.nf
export STAMP_WARN="Insufficient attention to detail. Look at me, $LOGIN!"
.fi
Change the apology to a demand for attention.
.TP
.nf
\fI\*(PN\fP \-k $USER
.fi
Terminate our test stamp process.
.TP
.nf
\fI\*(PN\fP \-M /tmp/s0 \-R localhost \-T 0 "TERM=$TERM" "TERMCAP=$TERMCAP"
.fi
Build a debug stamp with authorization data from localhost:1's
mux service named \*(lqroapmux\*(rq on \*lqlocalhost\*(rq.
.TP
.nf
\fI\*(PN\fP \-Q /tmp/s0 \-F TERMCAP
.fi
Ask the stamp created in the previous command for the TERMCAP
tableau entery (copied from out environment) in a format that \fBop\fP
would accept as external input from a jacket (helmet).
.TP
.nf
\fI\*(PN\fP \-Q /tmp/s0 \-F TERMCAP FAIL
.fi
This command does not output any tableau enties to \fIstdout\fP, because
no entry exists for \*(lqFAIL\*(rq.
.TP
.nf
\fI\*(PN\fP \-k /tmp/s0
.fi
Terminate the debug session.

.SH PROTOCOL

The chat protocol between the \fBstamp\fP(7l) jacket and \fI\*(PN\fP
is not really public, but to debug a running stamp an admin may need
to know the basics.  There are several useful commands for
debugging.  The single letter commands \fB?\fP displays status (\*(lqp\*(rq
for for penalty mode, or \*(lqy\*(rq for active), command \fBI\fP displays
the idle timeout, command \fBJ\fP displays the process-id.

.SH BUGS
One may specify an absolute path to a stamp, to put it anyplace in the
filesystem.  This is a bug in that there is absolutely no way to judge the
level of trust to give a stamp in a random directory.  It is a feature in
that this allows mortal sentinel instances of \fBop\fP to use stamps.

.SH AUTHOR
KS Braunsdorf
.br
NonPlayer Character Guild
.br
stamps at ksb dot npcguild.org

.SH "HTML"
See jacket.html in the source to op's jackets.

.SH "SEE ALSO"
.hlm 0
op(1l), sh(1), stamp(7l), op-jacket(7l), install.cf(5l)