stampctl - control the op authorization stamp facility
stampctl [-g group] [-m mode] [-u user] [facilities]
stampctl -M stamp [-n] [-max] [-D drop] [-E end] [-g group] [-I idle]
[-m mode] [-u user] [name[=value]s]
stampctl -M stamp -R roap [-nX] [-max] [-D drop] [-E end] [-g group]
[-I idle] [-m mode] [-p service] [-T timeout] [-u user] [name[=value]s]
stampctl -k|K|N [stamps]
stampctl -v [stamps]
stampctl -Q stamp [-F] [tableaus]
A stamp represents the authorization status of a person (group of peo-
ple) 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. Stampctl manages local authoriza-
tion stamps by creating, revoking, refreshing, and deleting these pro-
Mortal users may be allowed to create authorization stamps directly,
with an op 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 esca-
lated to the superuser, or to a dedicated mortal login (viz. "stamp",
aka Phil Atelies, in group "frankage").
The owner of the stamp socket does not have to match the owner of the
manager process. The stamp process drops to the drop login after cre-
ating 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.
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 all authorization requests until it expires. To
terminate the penalty mode a signal must be sent to the process (see
-K). The -n option starts a stamp in penalty mode.
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 cron(8) tasks, or to remove access by group, applica-
tion, or service.
A stamp may be created with advise from a remote authorization service,
under the -R option. This remote service is usually an instance of
roapmux(7l), which runs under the tcpmux(8) service. Any authorization
advise from the remote service is loaded before the requested tableau
(see -X below).
Set the maximum number of authorizations allowed by the new
stamp created under -M. When the count is exhausted, the stamp
terminates. Any number less than 1 rejects exactly 1 request,
Call setuid(2) to drop to the specified user (or user:group) to
process requests. The prevents the Customer from sending any
signals to the stamp process (or allows it if you like). Not
setting a drop leave the process owner as-is, which may inherit
them from op.
Specify a maximum time limit in scaled seconds (default "0", no
timeout). This uses the standard simple suffix table from
mkcmd(1l)'s seconds module. To be more like sudo specify 1h.
Under -Q output the requested tableaus in the format op requires
for external input of environment variables. This allows a
jacket to inject stamp data into an escalated process's environ-
Group ownership for the new stamp.
This program uses that same interface as the stamp(7l) jacket.
This common option explains the environment interface available,
since any op configuration sets environment variables to pass
preferences to jackets and helmets, and we use the same inter-
face when called from op.
Print only a brief help message.
Specify an idle timeout in scaled seconds (default "1h", 1
hour). To be more like sudo specify to 10m.
-k | -K stamps
Terminate an existing authorization provided by stamps, unless
these stamps are in penalty mode. The lowercase (k) 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.
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 (/) followed
by optional bits, see install.cf(5l).
Make an authorization for named stamp. The tableau of
name=value pairs specified after the options may be used as
environment variables by escalated process, or as credentials
for future helmet/jacket verification. See stamp(7l). If the
equal sign and the value are omitted, then the value is recov-
ered from the current environment. In that case, and if the
name is not set in the environment, the tableau entry is dis-
carded such that it would appear that the entry were never spec-
Start in penalty mode (never allow any escalations). This
locks-out the given stamp for a specific time (set with -I and
-E). Force the stamp to penalty mode. This might be used at
the end of change to prevent further escalations, but killing
the stamp has better effect, in that new escalations may com-
Connect to the tcpmux on the port listed for service. Service
may also be an explicit port number. The default service "tcp-
mux" is usually listed as port 1.
Request the tcpmux service mux from the host roap, rather than
the default roap:roapmux. This service may redirect the client
with a reply of @new-host:Inew-port. This is ksb's extension to
RFC1918 that is used to redirect clients as services migrate.
Under -R limit the connection to the roap service to timeout
seconds. This prevents slow authorization services from block-
ing stamp creation for a very long time.
Owner of the new stamp, and an optional group. The owner does
not have to be the Customer, in fact that's usually a very bad
idea. Also note that -D sets the new stamp's effective user ID,
which should never be the Customer's.
Reset the idle timeout for an existing authorization. This is
for compatibility with sudo(8), every access to the stamp resets
the idle timer as well.
Output only the version of the program, then exit.
Query the specified stamp for each tableau value. If all
tableau entries exist output them to stdout, else report the
failed entry on stderr and exit non-zero.
A remote tableau entry under -R usually overrides any suggested
local value. Under this switch the local tableau entry takes
Learn the version, default facility name (usually "stamp"), and
default cache directory.
stampctl -m 1777 -u phil -g frankage .
Build the default directory with liberal modes. Anyone may cre-
ate a stamp in the default directory. Without an escalation
rule to consult those stamps they are pretty useless. The phil
and frankage names are local site policy. Avoid using "nobody"
or "vanilla" as they get over-used all the time.
STAMP_FACILITY=. stampctl -m 750 -g wheel . admin
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.
STAMP_FACILITY=cat stampctl -m750/025 -gcat tiger puma lion jaguar
Build 4 facility directories with optional modes under the "cat"
stampctl -M $USER TERM="$TERM" TERMCAP="$TERMCAP" TTT='tty' ; export STAMP_SPEC="$USER"
Build a test stamp with 3 tableau entries.
/usr/local/libexec/jacket/stamp -- true /bin/true 0:0 auth:any ; echo $?
Test the stamp just created, just as op would. If this outputs
0 (success) then op would treat this authorization as valid.
Change the requested authorization to deny the current tty ses-
sion. Try the previous example again and it should fail (with
77) and the message "Sorry".
export STAMP_WARN="Insufficient attention to detail. Look at me, $LOGIN!"
Change the apology to a demand for attention.
stampctl -k $USER
Terminate our test stamp process.
stampctl -M /tmp/s0 -R localhost -T 0 "TERM=$TERM" "TERMCAP=$TERMCAP"
Build a debug stamp with authorization data from localhost:1's
mux service named "roapmux" on "localhost". Without that ser-
vice enables this will fail. See roapmux(7l).
stampctl -Q /tmp/s0 -F TERMCAP
Ask the stamp created in the previous command for the TERMCAP
tableau entry (copied from the environment) in a format that op
would accept as external input from a jacket (helmet).
stampctl -Q /tmp/s0 -F TERMCAP FAIL
This command does not output any tableau entries to stdout,
because no entry exists for "FAIL".
stampctl -k /tmp/s0
Terminate the debug session.
The chat protocol between the stamp(7l) jacket and stampctl 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 sin-
gle letter commands ? displays status ("p" for for penalty mode, or "y"
for active), command I displays the idle timeout, command J displays
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 fea-
ture in that this allows mortal sentinel instances of op to use stamps.
The actual time spent in penalty mode is the minimum of the idle and
end times. It might be clever for the stamp to set the idle time to
end when penatly more is set on the commnad-line. But if you are set-
ting it on the command-line, then you can do that: the current behavior
allows faster relief for miscreant clients who don't beat on the struc-
NonPlayer Character Guild
stamps at ksb dot npcguild.org
See jacket.html in the source to op's jackets.
op(1l), sh(1), stamp(7l), op-jacket(7l), install.cf(5l), roapmux(7l)