STAMPCTL(8)                                                        STAMPCTL(8)



NAME
       stampctl - control the op authorization stamp facility

SYNOPSIS
       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 -h
       stampctl -H
       stampctl -V
       stampctl -Q stamp [-F] [tableaus]

DESCRIPTION
       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-
       cesses.

       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).

OPTIONS
       -max
              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,
              then exits.

       -D drop
              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.

       -E end
              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.

       -F
              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-
              ment.

       -g group
              Group ownership for the new stamp.

       -H
              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.

       -h
              Print only a brief help message.

       -I idle
              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.

       -m mode
              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).

       -M stamp
              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-
              ified.

       -n
              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-
              mence.

       -p service
              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.

       -R roap[:mux]
              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.
              See tcpmux(8l).

       -T timeout
              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.

       -u user[:group]
              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.

       -v
              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.

       -V
              Output only the version of the program, then exit.

       -Q stamp
              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.

       -X
              A  remote tableau entry under -R usually overrides any suggested
              local value.  Under this switch the local  tableau  entry  takes
              precedence.

EXAMPLES
       stampctl -V
              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"
              topic.

       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.

       export STAMP_SPEC="$USER:TTY!'tty'"
              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.

PROTOCOL
       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
       the process-id.

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 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-
       ture.

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

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

SEE ALSO
       op(1l), sh(1), stamp(7l), op-jacket(7l), install.cf(5l), roapmux(7l)



                                     LOCAL                         STAMPCTL(8)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | PROTOCOL | BUGS | AUTHOR | HTML | SEE ALSO