1pseudo(1) General Commands Manual pseudo(1)
2
6 pseudo - run a command in a virtual root environment
7
9 pseudo [-dflv] [ -x flags ] [ -P prefix ] [ -rR root ] [ -t timeout ]
10 [command]
11 pseudo -h
13 pseudo [-dflv] [ -x flags ] [ -P prefix ] [-BC] -i path
15 pseudo [-dflv] [ -x flags ] [ -P prefix ] [-BC] -m from -M to
17 pseudo [-dflv] [ -x flags ] [ -P prefix ] -S
19 pseudo [-dflv] [ -x flags ] [ -P prefix ] -V
21
23 The pseudo utility provides a virtual root environment, hereafter
24 referred to as the pseudo environment, allowing the creation of file
25 system images and packages by users without root privileges. The
26 pseudo environment is implemented by pushing a special library
27 (libpseudo.so) into the LD_PRELOAD environment variable. This library
28 intercepts a large number of common filesystem operations and some
29 user-id related operations, and returns values that look as though the
30 operations had been performed by a root user. This is in turn managed
31 by a daemon program which keeps a list of virtualized file ownership
32 and permissions; this daemon program itself is pseudo.
33 The pseudo program itself can also be used as a program launcher. The
35 launcher is used to automatically configure a working environment, then
36 execute processes within that environment. Alternatively, you can
37 bypass this by setting up certain environment variables (see the ENVI‐
38 RONMENT section below). The pseudo client library (libpseudo.so) can
39 then start the server automatically.
40 The pseudo command can be invoked in one of several possible modes:
42 -B The -B option causes pseudo to scan its database, as with the
45 -C option, but instead of reporting mismatches, pseudo attempts
46 to repair them. Specifically, device and inode number mis‐
47 matches are corrected, and symlink or directory mismatches
48 result in deletion of database entries.
49 -C The -C option causes pseudo to scan its database, comparing
51 against the filesystem, and reporting likely errors. This may
52 be unreliable when the server is actively running.
53 -h The -h option causes pseudo to print a usage message and exit.
55 -i The -i option causes pseudo to attempt to correct device number
57 mismatches by checking inodes; if path has the same inode num‐
58 ber as recorded in the database, but a different device number,
59 all instances of the device number recorded in the database are
60 updated to the device number in the live filesystem for path.
61 This is intended to handle the mismatches that can occur when
62 remounting an NFS filesystem. The -i option implies the -C
63 option. You can also specify the -B option to request that the
64 database be rebuilt.
65 -m The -m and -M options cause pseudo to rename files, replacing
67 the string from with the string to. The -m option pair implies
68 the -C option. You can also specify the -B option to request
69 that the database be rebuilt.
70 -V The -V option causes pseudo to print configuration information
72 and exit immediately.
73 -S The -S option causes pseudo to try to find an existing server,
75 and if it finds one, instructs that server to shut down as soon
76 as all clients are detached from it. Note that the server will
77 not shut down while clients are connected to it; in this case,
78 pseudo will print a list of the remaining client PIDs.
79 -d The -d option causes pseudo to immediately detach and run in
81 the background as a daemon. This is rarely useful except for
82 debugging.
83 Finally, invoked without any of these options, pseudo sets up an emu‐
85 lated root environment, then invokes command if it was provided, other‐
86 wise a shell (using the SHELL environment variable if it is set, or
87 /bin/sh otherwise).
88 The following options modify the behavior of pseudo:
90 -d (daemonize)
93 Run as a daemon; pseudo detaches from the calling environment
94 and runs as a daemon. The command returns successfully if this
95 appears to have succeeded, otherwise it produces an error mes‐
96 sage and returns a failure status.
97 -f (foreground)
100 Run in the foreground; pseudo runs as a server, and does not
101 try to start other commands. This mode is useful for debug‐
102 ging.
103 -l (log)
106 Enable logging. The pseudo daemon will log every filesystem
107 transaction in the log database.
108 -r root
111 -R root Set the PSEUDO_CHROOT environment variable, running as though
113 the program had called chroot(2) on the specified path. With
114 -r, this implies changing the working directory to the speci‐
115 fied directory; with -R, it does not.
116 -t timeout
119 Set the timeout of the pseudo daemon, in seconds. The default
120 is currently 30 seconds. After this long with no attached
121 clients, the pseudo daemon shuts down automatically. The
122 server never shuts down while it has attached clients. Note
123 that this does not prevent continued use; new clients can
124 restart the daemon if they need it.
125 -v (verbose)
128 Increase the verbosity of the pseudo daemon, and the client
129 library for any programs started by this invocation of pseudo.
130 This is equivalent to the numeric form of the PSEUDO_DEBUG
131 environment variable; multiple -v options increase the debug‐
132 ging level.
133 -x (debug)
136 Set specific deugging flags (the pseudo utility's help message
137 lists them). This is equivalent to the string form of the
138 PSEUDO_DEBUG environment variable.
139
142 The two most common usages of pseudo are using it to run specific com‐
143 mands, and setting up an environment manually for running various other
144 commands.
145 For the first case, the usage is reasonably simple:
147 $ /path/to/pseudo
150 # commands which require root privileges
151 You may have to use the -Pprefix option to tell pseudo where to look
153 for its database and server. If you specify a full path, pseudo
154 assumes that PSEUDO_PREFIX should be the path to the directory contain‐
155 ing the pseudo program, or to the /bin directory containing the pseudo
156 program.
157 The other way to use pseudo is by setting up an environment. This is
159 suitable for use in Makefiles or similar environments, where you want
160 to run a series of commands in the pseudo environment, but not to keep
161 invoking the pseudo command. To do this, set up the PSEUDO_PRE‐
162 FIX, LD_PRELOAD, and LD_LIBRARY_PATH environment variables, then run
163 programs normally. You do not need to separately invoke the pseudo
164 daemon; the client library starts it as needed.
165 If you have moved a directory which pseudo was tracking, you may be
167 able to get the database reattached using the -m option. A typical
168 usage might be:
169 $ /path/to/pseudo -B -m oldpath -M newpath
172 This requests that pseudo replace the string oldpath with the string
174 newpath at the beginnings of filenames, then regenerate the database,
175 correcting any device/inode numbers.
176
179 Depending on invocation, diagnostic messages usually go either to stan‐
180 dard error or to the file PSEUDO_PREFIX /var/pseudo/pseudo.log. By
181 default, pseudo daemon messages go into the log file, but messages gen‐
182 erated by the client code go to standard error. These can be changed
183 using the PSEUDO_DEBUG_FILE environment variable, documented in ENVI‐
184 RONMENT. At the default logging level, only critical messages are dis‐
185 played. If you have raised the logging level (using the -v option or
186 the PSEUDO_DEBUG environment variable), additional messages are dis‐
187 played. Levels higher than 2 are very unlikely to be useful outside of
188 pseudo development.
189 Diagnostic messages seen by default are those which are believed to
191 indicate either a serious internal flaw in pseudo or a completely unex‐
192 pected failure from the underlying operating system. In normal use,
193 you should see no diagnostic messages.
194
197 The most significant environment variables for pseudo are LD_PRELOAD
198 and LD_LIBRARY_PATH. However, these variables have no special meaning
199 to pseudo; rather, they are used in the standard way to manipulate the
200 dynamic linker into loading the libpseudo library so that it can inter‐
201 cept calls into the underlying C library.
202 The following environment variables are used directly by pseudo:
204 PSEUDO_BINDIR
207 This directory holds the path to the pseudo binary; by default,
208 it is the bin directory under PSEUDO_PREFIX.
209 PSEUDO_CHROOT
211 This variable holds the current emulated chroot(2) path. Paths
212 that are relative to this are treated as though they were
213 instead relative to the filesystem root.
214 PSEUDO_DEBUG
216 This variable holds either a numeric "debug level" for pseudo
217 to run at, or a set of specific debugging flags, generally let‐
218 ters. Use pseudo -h to see the available flags. In general,
219 this is useful only for debugging pseudo itself.
220 PSEUDO_DEBUG_FILE
222 The name of a file to use for debugging messages from the
223 pseudo client; the default is to log to standard error. If the
224 string contains a single %s, that string is replaced with the
225 short program name, and if it contains a single %d, that string
226 is replaced with the process ID. Other format specifiers
227 (other than '%%') are not allowed. By default, the pseudo
228 server logs to the file pseudo.log in the var/pseudo directory,
229 while clients log to standard error.
230 PSEUDO_DISABLED
232 If this variable is set to a value that doesn't look like f, F,
233 n, N, s, S, or a numeric zero, the pseudo client library does
234 not modify the behavior of called functions, though it contin‐
235 ues to intercept them and block signals while processing them.
236 This variable is reevaluated on every call to fork(2), clone(2)
237 or related functions. If the value starts with a lowercase or
238 uppercase s , the pseudo client disables all server spawning
239 and communications, but still operates locally. This means that
240 no filesystem mode or permissions changes are actually recorded
241 or reported, but functions like chown() will still report suc‐
242 cess, even though nothing happens. This function is intended
243 for debugging of issues which are complicated by the server's
244 involvement.
245 PSEUDO_ALLOW_FSYNC
247 If this variable is set, pseudo will allow fsync() and related
248 system calls, even it was configured with the --enable-force-
249 async option. Otherwise, that option results in all such calls
250 being discarded silently, even when PSEUDO_DISABLED is set. The
251 value specified doesn't matter.
252 PSEUDO_ENOSYS_ABORT
254 If this variable is set, the pseudo client library calls
255 abort() rather than setting errno to ENOSYS in the event of a
256 call to a missing underlying function. This variable has no
257 function outside of debugging pseudo itself.
258 PSEUDO_LIBDIR
260 This directory holds the path to the pseudo shared libraries;
261 by default, it is the lib directory under PSEUDO_PREFIX. (On
262 64-bit hosts, lib64 is also used.)
263 PSEUDO_LOCALSTATEDIR
265 This directory holds the pseudo database files and log files;
266 by default, it is the var/pseudo directory under PSEUDO_PREFIX.
267 PSEUDO_NOSYMLINKEXP
269 By default, when chrooted, pseudo prepends the chroot directory
270 to the paths used for absolute symlinks; this behavior ensures
271 that opening symlinks produces expected results in most cases.
272 In some cases you may want to suppress this. If this variable
273 is unset, or set to any value other than 0, pseudo expands sym‐
274 link paths like this. If this variable is set to 0, the behav‐
275 ior is disabled.
276 PSEUDO_OPTS
278 This variable holds options to be passed to any new pseudo
279 servers started. Typically, when pseudo is used as a launcher,
280 this will be set automatically; however, you can also use it to
281 pass options when using LD_PRELOAD to manually run things in
282 the pseudo environment.
283 PSEUDO_PASSWD
285 This variable holds the path to a directory containing password
286 and group files to use for emulation of various password and
287 group routines. It should be the path to a directory contain‐
288 ing the etc directory containing files named passwd and group.
289 When pseudo is emulating a chroot environment, the chroot
290 directory is used by preference. The parallelism between these
291 cases is why this variable points at the parent directory of
292 etc rather than the directory containing the files. If there is
293 no chroot environment, and this variable is also unset, pseudo
294 falls back to a directory specified at configure time, with the
295 default being the root directory. This is controlled by the
296 PSEUDO_PASSWD_FALLBACK definition.
297 PSEUDO_PREFIX
299 If set, the variable PSEUDO_PREFIX is used to determine the
300 path to use to find the pseudo server, in PSEUDO_PREFIX/bin,
301 and the pseudo data files, in PSEUDO_PREFIX/var/pseudo. This
302 variable is automatically set by the pseudo program when it is
303 used as a launcher.
304 PSEUDO_PROFILE_PATH
306 If pseudo was configured with profiling enabled, specifies a
307 path in which to write client profiling information for use
308 with the pseudo_profile utility (not built by default).
309 PSEUDO_TAG
311 If this variable is set in a client's environment, its value is
312 communicated to the server at the beginning of each client ses‐
313 sion, and recorded in the log database if any logging occurs
314 related to a specific client. Note that different clients may
315 have different tags associated with them; the tag value is per-
316 client, not per-server.
317 PSEUDO_UIDS, PSEUDO_GIDS
319 These variables are used internally to pass information about
320 the current emulated user and group identity from one process
321 to another.
322 PSEUDO_UNLOAD
324 This variable is reevaluated on every call to fork(2), exec(3)
325 or related functions. If the variable exists libpseudo.so will
326 be removed from LD_PRELOAD and PSEUDO_DISABLED behavior will
327 also be triggered. For processes that simply fork(2), the
328 behavior will be the same as if PSEUDO_DISABLED was set. For
329 new processes, after a call to exec(3) or system(3) pseudo will
330 not be loaded in the new process.
331 SHELL If set, this will be used when pseudo is invoked without either
333 a command or one of the options which directs it to do some‐
334 thing other than run a command. Otherwise, pseudo defaults to
335 /bin/sh .
336
338 The pseudo database is not particularly robust in the face of whole
339 directory trees being moved, or changes in the underlying device and
340 inode numbers. It has a reasonable chance of recovering if only the
341 path or the device numbers have changed, but it is not particularly
342 designed to address this. A future release is expected to have
343 improved resilience in these cases.
344 The filesystem on which pseudo keeps its database and files must at a
346 minimum support UNIX domain sockets and reasonable file locking seman‐
347 tics. Note that pseudo relies on flock(2) locking semantics; a lock
348 has to persist into a child process. This should probably eventually
349 be fixed.
350 The pseudo client library is probably thread-safe, but has not been
352 adequately tested or debugged in that context.
353 Filesystem performance is noticably worse under pseudo than it is oth‐
355 erwise. This is probably because nearly every operation (other than
356 reads and writes) involves at least one round-trip network communica‐
357 tion with the server, and probably some kind of database activity.
358
361 fakeroot(1), ld.so(8), pseudolog(1), sqlite3(1)
362
364 Documentation of the internals of pseudo may be found in the doc subdi‐
365 rectory of the pseudo source tree.
366 pseudo - pretending to be root pseudo(1)