USERV(1)

📦 version 1.2.3, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

🌸 NAME 🌸

userv — request user services ✨ (yep, that's userv(1), the General Commands Manual one, and bestie it is long, so buckle up 🫶)

💖 SYNOPSIS 💖

userv [option ...] [--] service-user service-name [argument ...]
userv [option ...] -B | --builtin [--] builtin-service
      [info-argument ...]

🦋 DESCRIPTION 🦋

So like, userv is the whole point: you use it to have a task performed under a different userid, while keeping the trust between the caller and the callee limited. Lowkey iconic design, no cap. 👑

service-user tells you which user account is gonna perform the task. It can be a login name, or a numeric uid, or - to say "the service user is the same as the calling user, same girl, different hat". 💅

The service name is interpreted by the userv daemon on behalf of the service user. That's all controlled by configuration files in the service user's filespace, so go consult the userv specification for the details, iykyk. 📖

🌈 OPTIONS 🌈

Single-letter options can be combined like they usually are with Unix programs, and the value for such an option can show up in the same argument or in the next one. Classic. ✨

  • -B | --builtin — requests that a builtin service be provided. This is equivalent to using the --override option to specify a string made of ‘execute-builtin’ followed by the builtin-service requested, and requesting a service user of - (which means the calling user). 🎀

If the builtin service you're requesting needs a service-argument, then it has to be supplied to the client in the same argument as the builtin-service. See the specification, or the output of

userv -B help

for the details of the builtin services available, and see below for the details of the --override options.

The actual service name passed will be the builtin-service; note that this actual service name (as opposed to the override data) and the info-arguments supplied will be ignored by most builtin services; the override mechanism and ‘execute-builtin’ are used to make sure the right builtin service gets called with the right service-arguments. Trust the process. 💫

  • -f | --file fd[fdmodifiers]=filename — requests that data be copied in and out of the service using pipes 🚰. For each file or descriptor this is done by creating a pipe, one end of which is passed to the service program and the other end of which is passed to a copy of cat invoked by the client; the other file descriptor passed to cat will be one inherited by the client program from the caller, or one opened by the client program on behalf of the caller.

The descriptor in the service program that should be connected must be specified as fd, either as a decimal number or as one of the strings stdin, stdout or stderr. The next argument is a filename which will be opened by the client with the privileges of the calling user. 🔐

modifiers is used to specify whether the file or descriptor is to be read from or written to. It consists of a series of words separated by commas. A comma may separate the modifiers from the fd and is required if fd is not numeric. The modifier words are:

  • read — O_RDONLY: allow reading and not writing. May not be used with ‘write’ or things that imply it.
  • write — O_WRONLY: allow writing and not reading. Doesn't truncate or create without ‘truncate’ or ‘create’. ‘write’ or things that imply it may not be used with ‘read’.
  • overwrite — equivalent to ‘write,create,truncate’.
  • create, creat — O_CREAT: creates the file if necessary. Implies ‘write’.
  • exclusive, excl — O_EXCL: fails if the file already exists. Implies write and create. May not be used with ‘truncate’.
  • truncate, trunc — O_TRUNC: truncate any existing file. Implies ‘write’. May not be used with ‘exclusive’.
  • append — O_APPEND: all writes will append to the file. Implies ‘write’ (but not ‘create’).
  • sync — O_SYNC: do writes synchronously. Implies ‘write’.
  • wait, nowait, close — these modifiers control the behaviour of the client, with respect to the pipes carrying data to and from the service, when the service terminates. See below. 👀
  • fd — the filename is not a filename but a numeric file descriptor. One or both of ‘read’ and ‘write’ must be specified, and no other words are allowed. The filename may also be stdin, stdout or stderr for file descriptor 0, 1 or 2 respectively.

If no modifiers which imply ‘read’ or ‘write’ are used it is as if ‘write’ had been specified, except that if the file descriptor 0 of the service is being opened (either specified numerically or with ‘stdin’) it is as if ‘overwrite’ had been specified (or ‘write’ if only ‘fd’ was specified).

The client will also use O_NOCTTY when opening files specified by the caller, to avoid changing its controlling terminal.

By default stdin, stdout and stderr of the service will be connected to the corresponding descriptors on the client. Diagnostics from the client and daemon will also appear on stderr.

If ‘wait’ is specified, the client will wait for the pipe to be closed, and only exit after this has happened. This means that either the receiving end of the pipe connection was closed while data was still available at the sending end, or that the end of file was reached on the reading file descriptor. Errors encountered reading or writing in the client at this stage will be considered a system error and cause the client to exit with status 255, but will not cause disconnection at the service side since the service has already exited. 😭

If ‘close’ is specified the client will immediately close the pipe connection by killing the relevant copy of cat. If the service uses the descriptor it will get SIGPIPE (or EPIPE) for a writing descriptor or end of file for a reading one; the descriptor opened by or passed to the client will also be closed. 💀

If ‘nowait’ is specified then the client will not wait and the connection will remain open after the client terminates. Data may continue to be passed between the inheritors of the relevant descriptor on the service side and the corresponding file or descriptor on the client side until either side closes their descriptor. This should not usually be specified for stderr (or stdout if --signals stdout is used) since diagnostics from the service side may arrive after the client has exited and be confused with expected output. 🙈

The default is ‘wait’ for writing file descriptors and ‘close’ for reading ones.

  • -w | --fdwait fd=action — sets the action on termination of the service for the specified file descriptor; action must be ‘wait’, ‘nowait’ or ‘close’ as described above. The file descriptor must be specified as open when this option is encountered; this option is overridden by any later --file or --fdwait option — even by a --file which does not specify an action on termination (in this case the default will be used, as described above). Last one wins, periodt. 💅
  • -D | --defvar name=value — set a user-defined variable name to value. These user-defined variables are made available in the configuration language as the parameters ‘u-name’ and are passed to the service in environment variables USERV_U_name. name may contain only alphanumerics and underscores, and must start with a letter. If several definitions are given for the same name then only the last is effective. 🍓
  • -t | --timeout seconds — time out the service if it takes longer than seconds seconds (a positive integer, in decimal). Timeout will produce a diagnostic on stderr and an exit status of 255. If seconds is zero then no timeout will be implemented (this is the default). ⏰
  • -S | --signals method — affects the handling of the exit status when the service terminates due to a signal. (The client will always finish by calling _exit(), so that only numbers from 0 to 255 can be returned and not the full range of numbers and signal indications which can be returned by the wait() family of system calls.) 🫶

The method may be one of the following:

  • status — the client's exit status will be status. This will not be distinguishable from the service really having exited with code status. This method is the default, with a status of 254.
  • number, number-nocore — the client's exit status becomes the number of the signal that killed the service 💀. If you say number instead of number-nocore, then 128 gets added on top when the service dumped core. And number? It's basically the same exit-code mangling the Bourne shell does, iykyk.
  • highbit — the client's exit status = the signal number plus 128. And if the service exits totally normally with an exit code above 127? Then you just get 127 back. Rude but true.
  • stdout — this one's a lil extra, bestie. The service's numeric wait status gets printed as two decimal numbers (high byte first) plus a whole textual description of what it means, and all of that goes to the client's standard output. There's a newline in front of it and an extra newline after it, and the numbers are separated from each other and from the description by single spaces. The client's exit status is zero — UNLESS a system error happens, in which case nothing gets printed to stdout (no exit status, no description, nada) and an error message goes to stderr like usual.

So what counts as a system error? Client usage errors, the service not being found, permission being denied, or a system call just failing. When that happens an error message explaining the whole situation goes to the client's stderr and the client's exit status is 255. And if the client dies because of a signal? Treat that as a serious system error, no cap.

  • -H, --hidecwd — stops the calling process's current directory name from being handed to the service. Instead, the null string gets passed. Poof, gone 🫥.
  • -P, --sigpipe — if the service program gets terminated by a SIGPIPE, the client's exit status is zero, even if the exit status method you picked would've said something else entirely. Tiny caveat: this option does nothing to the code and description printed when you're using the stdout exit status method. No effect. Zero. None 💅.
  • -h, --help — prints the client's usage message. Classic.
  • --copyright — prints the copyright and the lack-of-warranty notice. The legal girlies ate.

🔐 SECURITY-OVERRIDING OPTIONS 🔐

Okay so these are the big-girl options. They exist for debugging and to let the system administrator override a user's policy. And they are only available if the client is called by root, or if the calling user is the same as the service user. That's the vibe check, and if you don't pass it, you don't get in 🚫.

  • --override configuration-data
  • --override-file file — do NOT read the usual config files. Instead, the client sends either configuration-data (with a newline tacked on the end) or the contents of filename (which gets opened in the context of the client) straight to the daemon, and the daemon uses that instead. Heads up: the configuration-data has to all be in one single argument. A single newline will be appended so that one lone directive is easy to hand over, but if you need more than one directive, you're gonna have to put one or more real newlines in there yourself.
  • --spoof-user user — pretend to the service that it's being called by user (which can be a username or a uid). This also changes the group and supplementary groups handed to the service — they'll be the standard group and supplementary groups for user. One lil exception though: --spoof-user does not change which user gets chosen if the service user is specified as just -. In that case, the service user is the real calling user. Periodt.

🌿 ENVIRONMENT 🌿

  • LOGNAME, USER — these get used to figure out the name of the calling user, which then gets passed to the service in USERV_USER. Their values are only trusted if they actually correspond to the calling UID. Like, we check IDs around here 🕵️‍♀️.

📁 FILES 📁

  • /var/run/userv/socket — the Unix-domain socket used for communication between userv and uservd. The group chat line, basically.
  • /var/run/userv/%x.%x.%x — the pipes used for connecting file descriptors in the client and the service.

👀 SEE ALSO 👀

  • uservd(8)
  • Ian Jackson, User service daemon and client specification.

GNU userv is copyright Ian Jackson and other contributors. See README or userv --copright for full authorship information. (Yes, that's how it's spelled in the original, bestie — I'm not touching it 🙈.)

GNU userv is licensed under the terms of the GNU General Public Licence, version 3 or (at your option) any later version, and it comes with NO WARRANTY, not even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for details.

You should have received a copy of the GNU General Public License along with userv; if not, see http://www.gnu.org/licenses/

🦋 HISTORY 🦋

userv was initially written in 1996 by Ian Jackson. It became GNU userv in 1999, and version 1.0 was released in 2000. A true elder icon, honestly 🌈.

and that's the whole page, bestie — userv, from the November 3, 1999 edition of the USERV(1) manual, living its best life as part of the GNU userv 1.0 era. slay, drink water, and never pass --override unless you're literally root 💖✨🎀

📦 where this page comes from