Provided by: pseudo_1.9.0+git20230301+ec6151a2b057-1_amd64 
NAME
pseudo - run a command in a virtual root environment
SYNOPSIS
pseudo [-dflv] [ -x flags ] [ -P prefix ] [ -rR root ] [ -t timeout ] [command]
pseudo -h
pseudo [-dflv] [ -x flags ] [ -P prefix ] [-BC] -i path
pseudo [-dflv] [ -x flags ] [ -P prefix ] [-BC] -m from -M to
pseudo [-dflv] [ -x flags ] [ -P prefix ] -S
pseudo [-dflv] [ -x flags ] [ -P prefix ] -V
DESCRIPTION
The pseudo utility provides a virtual root environment, hereafter referred to as the pseudo environment,
allowing the creation of file system images and packages by users without root privileges. The pseudo
environment is implemented by pushing a special library (libpseudo.so) into the LD_PRELOAD environment
variable. This library intercepts a large number of common filesystem operations and some user-id
related operations, and returns values that look as though the operations had been performed by a root
user. This is in turn managed by a daemon program which keeps a list of virtualized file ownership and
permissions; this daemon program itself is pseudo.
The pseudo program itself can also be used as a program launcher. The launcher is used to automatically
configure a working environment, then execute processes within that environment. Alternatively, you can
bypass this by setting up certain environment variables (see the ENVIRONMENT section below). The pseudo
client library (libpseudo.so) can then start the server automatically.
The pseudo command can be invoked in one of several possible modes:
-B The -B option causes pseudo to scan its database, as with the -C option, but instead of reporting
mismatches, pseudo attempts to repair them. Specifically, device and inode number mismatches are
corrected, and symlink or directory mismatches result in deletion of database entries.
-C The -C option causes pseudo to scan its database, comparing against the filesystem, and reporting
likely errors. This may be unreliable when the server is actively running.
-h The -h option causes pseudo to print a usage message and exit.
-i The -i option causes pseudo to attempt to correct device number mismatches by checking inodes; if
path has the same inode number as recorded in the database, but a different device number, all
instances of the device number recorded in the database are updated to the device number in the
live filesystem for path. This is intended to handle the mismatches that can occur when
remounting an NFS filesystem. The -i option implies the -C option. You can also specify the -B
option to request that the database be rebuilt.
-m The -m and -M options cause pseudo to rename files, replacing the string from with the string to.
The -m option pair implies the -C option. You can also specify the -B option to request that the
database be rebuilt.
-V The -V option causes pseudo to print configuration information and exit immediately.
-S The -S option causes pseudo to try to find an existing server, and if it finds one, instructs
that server to shut down as soon as all clients are detached from it. Note that the server will
not shut down while clients are connected to it; in this case, pseudo will print a list of the
remaining client PIDs.
-d The -d option causes pseudo to immediately detach and run in the background as a daemon. This is
rarely useful except for debugging.
Finally, invoked without any of these options, pseudo sets up an emulated root environment, then invokes
command if it was provided, otherwise a shell (using the SHELL environment variable if it is set, or
/bin/sh otherwise).
The following options modify the behavior of pseudo:
-d (daemonize)
Run as a daemon; pseudo detaches from the calling environment and runs as a daemon. The command
returns successfully if this appears to have succeeded, otherwise it produces an error message
and returns a failure status.
-f (foreground)
Run in the foreground; pseudo runs as a server, and does not try to start other commands. This
mode is useful for debugging.
-l (log)
Enable logging. The pseudo daemon will log every filesystem transaction in the log database.
-r root
-R root Set the PSEUDO_CHROOT environment variable, running as though the program had called chroot(2) on
the specified path. With -r, this implies changing the working directory to the specified
directory; with -R, it does not.
-t timeout
Set the timeout of the pseudo daemon, in seconds. The default is currently 30 seconds. After
this long with no attached clients, the pseudo daemon shuts down automatically. The server never
shuts down while it has attached clients. Note that this does not prevent continued use; new
clients can restart the daemon if they need it.
-v (verbose)
Increase the verbosity of the pseudo daemon, and the client library for any programs started by
this invocation of pseudo. This is equivalent to the numeric form of the PSEUDO_DEBUG
environment variable; multiple -v options increase the debugging level.
-x (debug)
Set specific deugging flags (the pseudo utility's help message lists them). This is equivalent to
the string form of the PSEUDO_DEBUG environment variable.
EXAMPLES
The two most common usages of pseudo are using it to run specific commands, and setting up an environment
manually for running various other commands.
For the first case, the usage is reasonably simple:
$ /path/to/pseudo
# commands which require root privileges
You may have to use the -Pprefix option to tell pseudo where to look for its database and server. If you
specify a full path, pseudo assumes that PSEUDO_PREFIX should be the path to the directory containing the
pseudo program, or to the /bin directory containing the pseudo program.
The other way to use pseudo is by setting up an environment. This is suitable for use in Makefiles or
similar environments, where you want to run a series of commands in the pseudo environment, but not to
keep invoking the pseudo command. To do this, set up the PSEUDO_PREFIX, LD_PRELOAD, and LD_LIBRARY_PATH
environment variables, then run programs normally. You do not need to separately invoke the pseudo
daemon; the client library starts it as needed.
If you have moved a directory which pseudo was tracking, you may be able to get the database reattached
using the -m option. A typical usage might be:
$ /path/to/pseudo -B -m oldpath -M newpath
This requests that pseudo replace the string oldpath with the string newpath at the beginnings of
filenames, then regenerate the database, correcting any device/inode numbers.
DIAGNOSTICS
Depending on invocation, diagnostic messages usually go either to standard error or to the file
PSEUDO_PREFIX /var/pseudo/pseudo.log. By default, pseudo daemon messages go into the log file, but
messages generated by the client code go to standard error. These can be changed using the
PSEUDO_DEBUG_FILE environment variable, documented in ENVIRONMENT. At the default logging level, only
critical messages are displayed. If you have raised the logging level (using the -v option or the
PSEUDO_DEBUG environment variable), additional messages are displayed. Levels higher than 2 are very
unlikely to be useful outside of pseudo development.
Diagnostic messages seen by default are those which are believed to indicate either a serious internal
flaw in pseudo or a completely unexpected failure from the underlying operating system. In normal use,
you should see no diagnostic messages.
ENVIRONMENT
The most significant environment variables for pseudo are LD_PRELOAD and LD_LIBRARY_PATH. However, these
variables have no special meaning to pseudo; rather, they are used in the standard way to manipulate the
dynamic linker into loading the libpseudo library so that it can intercept calls into the underlying C
library.
The following environment variables are used directly by pseudo:
PSEUDO_BINDIR
This directory holds the path to the pseudo binary; by default, it is the bin directory under
PSEUDO_PREFIX.
PSEUDO_CHROOT
This variable holds the current emulated chroot(2) path. Paths that are relative to this are
treated as though they were instead relative to the filesystem root.
PSEUDO_DEBUG
This variable holds either a numeric "debug level" for pseudo to run at, or a set of specific
debugging flags, generally letters. Use pseudo -h to see the available flags. In general, this
is useful only for debugging pseudo itself.
PSEUDO_DEBUG_FILE
The name of a file to use for debugging messages from the pseudo client; the default is to log to
standard error. If the string contains a single %s, that string is replaced with the short
program name, and if it contains a single %d, that string is replaced with the process ID. Other
format specifiers (other than '%%') are not allowed. By default, the pseudo server logs to the
file pseudo.log in the var/pseudo directory, while clients log to standard error.
PSEUDO_DISABLED
If this variable is set to a value that doesn't look like f, F, n, N, s, S, or a numeric zero,
the pseudo client library does not modify the behavior of called functions, though it continues
to intercept them and block signals while processing them. This variable is reevaluated on every
call to fork(2), clone(2) or related functions. If the value starts with a lowercase or uppercase
s , the pseudo client disables all server spawning and communications, but still operates
locally. This means that no filesystem mode or permissions changes are actually recorded or
reported, but functions like chown() will still report success, even though nothing happens. This
function is intended for debugging of issues which are complicated by the server's involvement.
PSEUDO_ALLOW_FSYNC
If this variable is set, pseudo will allow fsync() and related system calls, even it was
configured with the --enable-force-async option. Otherwise, that option results in all such calls
being discarded silently, even when PSEUDO_DISABLED is set. The value specified doesn't matter.
PSEUDO_ENOSYS_ABORT
If this variable is set, the pseudo client library calls abort() rather than setting errno to
ENOSYS in the event of a call to a missing underlying function. This variable has no function
outside of debugging pseudo itself.
PSEUDO_LIBDIR
This directory holds the path to the pseudo shared libraries; by default, it is the lib directory
under PSEUDO_PREFIX. (On 64-bit hosts, lib64 is also used.)
PSEUDO_LOCALSTATEDIR
This directory holds the pseudo database files and log files; by default, it is the var/pseudo
directory under PSEUDO_PREFIX.
PSEUDO_NOSYMLINKEXP
By default, when chrooted, pseudo prepends the chroot directory to the paths used for absolute
symlinks; this behavior ensures that opening symlinks produces expected results in most cases.
In some cases you may want to suppress this. If this variable is unset, or set to any value
other than 0, pseudo expands symlink paths like this. If this variable is set to 0, the behavior
is disabled.
PSEUDO_OPTS
This variable holds options to be passed to any new pseudo servers started. Typically, when
pseudo is used as a launcher, this will be set automatically; however, you can also use it to
pass options when using LD_PRELOAD to manually run things in the pseudo environment.
PSEUDO_PASSWD
This variable holds the path to a directory containing password and group files to use for
emulation of various password and group routines. It should be the path to a directory
containing the etc directory containing files named passwd and group. When pseudo is emulating a
chroot environment, the chroot directory is used by preference. The parallelism between these
cases is why this variable points at the parent directory of etc rather than the directory
containing the files. If there is no chroot environment, and this variable is also unset, pseudo
falls back to a directory specified at configure time, with the default being the root directory.
This is controlled by the PSEUDO_PASSWD_FALLBACK definition.
PSEUDO_PREFIX
If set, the variable PSEUDO_PREFIX is used to determine the path to use to find the pseudo
server, in PSEUDO_PREFIX/bin, and the pseudo data files, in PSEUDO_PREFIX/var/pseudo. This
variable is automatically set by the pseudo program when it is used as a launcher.
PSEUDO_PROFILE_PATH
If pseudo was configured with profiling enabled, specifies a path in which to write client
profiling information for use with the pseudo_profile utility (not built by default).
PSEUDO_TAG
If this variable is set in a client's environment, its value is communicated to the server at the
beginning of each client session, and recorded in the log database if any logging occurs related
to a specific client. Note that different clients may have different tags associated with them;
the tag value is per-client, not per-server.
PSEUDO_UIDS, PSEUDO_GIDS
These variables are used internally to pass information about the current emulated user and group
identity from one process to another.
PSEUDO_UNLOAD
This variable is reevaluated on every call to fork(2), exec(3) or related functions. If the
variable exists libpseudo.so will be removed from LD_PRELOAD and PSEUDO_DISABLED behavior will
also be triggered. For processes that simply fork(2), the behavior will be the same as if
PSEUDO_DISABLED was set. For new processes, after a call to exec(3) or system(3) pseudo will not
be loaded in the new process.
SHELL If set, this will be used when pseudo is invoked without either a command or one of the options
which directs it to do something other than run a command. Otherwise, pseudo defaults to /bin/sh
.
BUGS
The pseudo database is not particularly robust in the face of whole directory trees being moved, or
changes in the underlying device and inode numbers. It has a reasonable chance of recovering if only the
path or the device numbers have changed, but it is not particularly designed to address this. A future
release is expected to have improved resilience in these cases.
The filesystem on which pseudo keeps its database and files must at a minimum support UNIX domain sockets
and reasonable file locking semantics. Note that pseudo relies on flock(2) locking semantics; a lock has
to persist into a child process. This should probably eventually be fixed.
The pseudo client library is probably thread-safe, but has not been adequately tested or debugged in that
context.
Filesystem performance is noticably worse under pseudo than it is otherwise. This is probably because
nearly every operation (other than reads and writes) involves at least one round-trip network
communication with the server, and probably some kind of database activity.
SEE ALSO
fakeroot(1), ld.so(8), pseudolog(1), sqlite3(1)
FURTHER READING
Documentation of the internals of pseudo may be found in the doc subdirectory of the pseudo source tree.
pseudo - pretending to be root pseudo(1)