aboutsummaryrefslogtreecommitdiffstats
path: root/pseudo.1
diff options
context:
space:
mode:
Diffstat (limited to 'pseudo.1')
-rw-r--r--pseudo.1353
1 files changed, 353 insertions, 0 deletions
diff --git a/pseudo.1 b/pseudo.1
new file mode 100644
index 0000000..35c3c69
--- /dev/null
+++ b/pseudo.1
@@ -0,0 +1,353 @@
+.\"
+.\" pseudo(1) man page
+.\"
+.\" Copyright (c) 2010 Wind River Systems, Inc.
+.\"
+.\" This program is free software; you can redistribute it and/or modify
+.\" it under the terms of the Lesser GNU General Public License version 2.1 as
+.\" published by the Free Software Foundation.
+.\"
+.\" This program is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.\" See the Lesser GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the Lesser GNU General Public License
+.\" version 2.1 along with this program; if not, write to the Free Software
+.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+.TH pseudo 1 "pseudo - pretending to be root"
+.SH SYNOPSIS
+.B pseudo
+.RB [ \-dflv ]
+.RB [ \-P\ prefix ]
+.RB [ \-t\ timeout ]
+.RB [ command ]
+.PP
+.B pseudo
+.RB [ \-P\ prefix ]
+.B \-S
+.PP
+.B pseudo
+.RB [ \-P\ prefix ]
+.B \-V
+.SH DESCRIPTION
+The
+.I pseudo
+utility provides a virtual root environment, hereafter referred to as the
+.IR 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
+.RI ( libpseudo.so )
+into the
+.B 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
+.IR pseudo .
+
+The
+.I 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
+.B ENVIRONMENT
+section below). The
+.I pseudo
+client library
+.RI ( libpseudo.so )
+can then start the server automatically.
+
+The
+.I pseudo
+command can be invoked in one of four possible modes:
+
+.TP 8
+.B \-V
+The
+.B \-V
+option causes
+.I pseudo
+to print configuration information and exit immediately.
+.TP 8
+.B \-S
+The
+.B \-S
+option causes
+.I 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,
+.I pseudo
+will print a list of the remaining client PIDs.
+.TP 8
+.B \-d
+The
+.B \-d
+option causes pseudo to immediately detach and run in the background
+as a daemon. This is rarely useful except for debugging.
+.PP
+Finally, invoked without any of these options,
+.I pseudo
+sets up an emulated root environment, then invokes
+.I command
+if it was provided, otherwise a shell (using the
+.B SHELL
+environment variable if it is set, or
+.I /bin/sh
+otherwise).
+
+The following options modify the behavior of
+.IR pseudo :
+
+.TP 8
+.BI \-d\ (daemonize)
+Run as a daemon;
+.I 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.
+
+.BI \-f\ (foreground)
+Run in the foreground;
+.I pseudo
+runs as a server, and does not try to start other commands. This mode
+is useful for debugging.
+
+.BI \-l\ (log)
+Enable logging. The
+.I pseudo
+daemon will log every filesystem transaction in the log database.
+
+.B \-t timeout
+Set the timeout of the
+.I pseudo
+daemon, in seconds. The default is currently 30 seconds. After this
+long with no attached clients, the
+.I 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.
+
+.BI \-v\ (verbose)
+Increase the verbosity of the
+.I pseudo
+daemon, and the client library for any programs started by this
+invocation of
+.IR pseudo .
+This is equivalent to the
+.B PSEUDO_DEBUG
+environment variable; multiple
+.B \-v
+options increase the debugging level.
+
+.SH EXAMPLES
+The two most common usages of
+.I 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:
+
+.sp
+$
+.I /path/to/pseudo
+.br
+#
+.I commands which require root privileges
+
+You may have to use the
+.BI \-P prefix
+option to tell
+.I pseudo
+where to look for its database and server. If you specify a full path,
+.I pseudo
+assumes that
+.B PSEUDO_PREFIX
+should be the path to the directory containing the
+.I pseudo
+program, or to the
+.I /bin
+directory containing the
+.I pseudo
+program.
+
+The other way to use
+.I pseudo
+is by setting up an environment. This is suitable for use in
+.I Makefiles
+or similar environments, where you want to run a series of commands in
+the
+.I pseudo
+environment, but not to keep invoking the
+.I pseudo
+command. To do this, set up the
+.BR PSEUDO_PREFIX ,\ LD_PRELOAD ,\ and\ LD_LIBRARY_PATH
+environment variables, then run programs normally. You do not need to
+separately invoke the
+.I pseudo
+daemon; the client library starts it as needed.
+
+.SH DIAGNOSTICS
+Depending on invocation, diagnostic messages usually go either to standard
+error or to the file
+.B PSEUDO_PREFIX
+.IR /var/pseudo/pseudo.log .
+By default,
+.I pseudo
+daemon messages go into the log file, but messages generated by the client
+code go to standard error. At the default logging level, only critical
+messages are displayed. If you have raised the logging level (using the
+.I \-v
+option or the
+.B PSEUDO_DEBUG
+environment variable), additional messages are displayed. Levels higher
+than 2 are very unlikely to be useful outside of
+.I pseudo
+development.
+
+Diagnostic messages seen by default are those which are believed to indicate
+either a serious internal flaw in
+.I pseudo
+or a completely unexpected failure from the underlying operating system. In
+normal use, you should see no diagnostic messages.
+
+.SH ENVIRONMENT
+The most significant environment variables for
+.I pseudo
+are
+.B LD_PRELOAD
+and
+.BR LD_LIBRARY_PATH .
+However, these variables have no special meaning to
+.IR pseudo ;
+rather, they are used in the standard way to manipulate the dynamic linker
+into loading the
+.I libpseudo
+library so that it can intercept calls into the underlying C library.
+
+The following environment variables are used directly by
+.IR pseudo :
+
+.TP 8
+.B PSEUDO_DEBUG
+This variable holds the "debug level" for
+.I pseudo
+to run at. In general, this is useful only for debugging
+.I pseudo
+itself.
+.TP 8
+.B PSEUDO_ENOSYS_ABORT
+If this variable is set, the
+.I pseudo
+client library calls
+.I abort()
+rather than setting
+.I errno
+to
+.B ENOSYS
+in the event of a call to a missing underlying function. This variable has
+no function outside of debugging
+.I pseudo
+itself.
+.TP 8
+.BR PSEUDO_OPTS
+This variable holds options to be passed to any new
+.I pseudo
+servers started. Typically, when
+.I pseudo
+is used as a launcher, this will be set automatically; however, you
+can also use it to pass options when using
+.B LD_PRELOAD
+to manually run things in the
+.I pseudo
+environment.
+.TP 8
+.B PSEUDO_PREFIX
+If set, the variable
+.B PSEUDO_PREFIX
+is used to determine the path to use to find the
+.I pseudo
+server, in
+.BR PSEUDO_PREFIX /bin,
+and the
+.I pseudo
+data files, in
+.BR PSEUDO_PREFIX /var/pseudo.
+This variable is automatically set by the
+.I pseudo
+program when it is used as a launcher.
+.TP 8
+.B PSEUDO_RELOADED
+This purely internal variable is used to track state while trying
+to re-execute to get rid of the
+.B LD_PRELOAD
+value when spawning a server. (The
+.I pseudo
+server itself cannot function running in the
+.I pseudo environment.)
+.TP 8
+.B 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.
+.TP 8
+.BR 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.
+.TP 8
+.B SHELL
+If set, this will be used when
+.I pseudo
+is invoked without either a command or one of the options which directs
+it to do something other than run a command. Otherwise,
+.I pseudo
+defaults to
+.I /bin/sh .
+.B
+.SH BUGS
+The
+.I 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
+.I pseudo
+keeps its database and files must at a minimum support UNIX domain sockets
+and reasonable file locking semantics. Note that
+.I pseudo
+relies on
+.I flock(2)
+locking semantics; a lock has to persist into a child process. This should
+probably eventually be fixed.
+
+The
+.I pseudo
+client library is probably thread-safe, but has not been adequately tested
+or debugged in that context.
+
+Filesystem performance is noticably worse under
+.I 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.
+
+.SH SEE ALSO
+fakeroot(1), ld.so(8), pseudolog(1), sqlite3(1)
+.SH FURTHER READING
+Documentation of the internals of
+.I pseudo
+may be found in the
+.I doc
+subdirectory of the pseudo source tree.