.TH "parrot_run" 1 "" "CCTools 7.1.2 FINAL" "Cooperative Computing Tools"

.SH NAME
.LP
\fBparrot_run\fP - run a program in the Parrot virtual file system

.SH SYNOPSIS
.LP
\FC\fBparrot_run [parrot_options] program [program_options]\fP\FT

.SH DESCRIPTION
.LP
\FCparrot_run\FT runs an application or a shell inside the Parrot virtual filesystem.  Parrot redirects the application's system calls to remote storage systems.  Parrot currently supports the following remote storage systems: HTTP, GROW, FTP, GridFTP, iRODS, HDFS, XRootd, Chirp.  This list may vary depending on how Parrot was built.  Run \FCparrot -h\FT to see exactly what support is available on your system.
.PP
Parrot works by trapping the application's system calls through the \FCptrace\FT debugging interface.  It does not require any special privileges to install or run, so it is useful to ordinary users that wish to access data across wide area networks.  The \FCptrace\FT debugging interface does have some cost, so applications may run slower, depending on how many I/O operations they perform.
.PP
For complete details with examples, see the Parrot User's Manual (\fBhttp://ccl.cse.nd.edu/software/manuals/parrot.html\fP)

.SH OPTIONS
.LP
.LP
.TP
.BI \ --check-driver \ <driver>
.
 Check for the presence of a given driver (e.g. http, ftp, etc) and return success if it is currently enabled.
.TP
\fB-a\fP, \fB-\-chirp-auth\fP=\fI<unix|hostname|ticket|globus|kerberos>\fP
.
Use this Chirp authentication method.  May be invoked multiple times to indicate a preferred list, in order.
.TP
\fB-b\fP, \fB-\-block-size\fP=\fI<bytes>\fP
.
Set the I/O block size hint.
.TP
\fB-c\fP, \fB-\-status-file\fP=\fI<file>\fP
.
Print exit status information to file.
.TP
.B \ -C
.
Enable data channel authentication in GridFTP.
.TP
\fB-d\fP, \fB-\-debug\fP=\fI<flag>\fP
.
Enable debugging for this sub-system.
.TP
.B \ -D
.
Disable small file optimizations.
.TP
.B \ --dynamic-mounts
.
 Enable the use of parot_mount in this session.
.TP
.B \ -F
.
Enable file snapshot caching for all protocols.
.TP
.B \ -f
.
Disable following symlinks.
.TP
\fB-G\fP, \fB-\-gid\fP=\fI<num>\fP
.
Fake this gid; Real gid stays the same.
.TP
.B \ -h
.
Show this screen.
.TP
.B \ --helper
.
Enable use of helper library.
.TP
\fB-i\fP, \fB-\-tickets\fP=\fI<files>\fP
.
Comma-delimited list of tickets to use for authentication.
.TP
\fB-I\fP, \fB-\-debug-level-irods\fP=\fI<num>\fP
.
Set the iRODS driver internal debug level.
.TP
.B \ -K
.
Checksum files where available.
.TP
.B \ -k
.
Do not checksum files.
.TP
\fB-l\fP, \fB-\-ld-path\fP=\fI<path>\fP
.
Path to ld.so to use.
.TP
\fB-m\fP, \fB-\-ftab-file\fP=\fI<file>\fP
.
Use this file as a mountlist.
.TP
\fB-M\fP, \fB-\-mount\fP=\fI</foo=/bar>\fP
.
Mount (redirect) /foo to /bar.
.TP
\fB-e\fP, \fB-\-env-list\fP=\fI<path>\fP
.
Record the environment variables.
.TP
\fB-n\fP, \fB-\-name-list\fP=\fI<path>\fP
.
Record all the file names.
.TP
.B \ --no-set-foreground
.
Disable changing the foreground process group of the session.
.TP
\fB-N\fP, \fB-\-hostname\fP=\fI<name>\fP
.
Pretend that this is my hostname.
.TP
\fB-o\fP, \fB-\-debug-file\fP=\fI<file>\fP
.
Write debugging output to this file. By default, debugging is sent to stderr (":stderr"). You may specify logs be sent to stdout (":stdout"), to the system syslog (":syslog"), or to the systemd journal (":journal").
.TP
\fB-O\fP, \fB-\-debug-rotate-max\fP=\fI<bytes>\fP
.
Rotate debug files of this size.
.TP
\fB-p\fP, \fB-\-proxy\fP=\fI<host:port>\fP
.
Use this proxy server for HTTP requests.
.TP
.B \ -Q
.
Inhibit catalog queries to list /chirp.
.TP
\fB-r\fP, \fB-\-cvmfs-repos\fP=\fI<repos>\fP
.
CVMFS repositories to enable (PARROT_CVMFS_REPO).
.TP
.B \ --cvmfs-repo-switching
.
 Allow repository switching with CVMFS.
.TP
\fB-R\fP, \fB-\-root-checksum\fP=\fI<cksum>\fP
.
Enforce this root filesystem checksum, where available.
.TP
.B \ -s
.
Use streaming protocols without caching.
.TP
.B \ -S
.
Enable whole session caching for all protocols.
.TP
.B \ --syscall-disable-debug
.
Disable tracee access to the Parrot debug syscall.
.TP
\fB-t\fP, \fB-\-tempdir\fP=\fI<dir>\fP
.
Where to store temporary files.
.TP
\fB-T\fP, \fB-\-timeout\fP=\fI<time>\fP
.
Maximum amount of time to retry failures.
time)Maximum amount of time to retry failures.
.TP
.B \ --time-stop
.
 Stop virtual time at midnight, Jan 1st, 2001 UTC.
.TP
.B \ --time-warp
.
 Warp virtual time starting from midnight, Jan 1st, 2001 UTC.
.TP
\fB-U\fP, \fB-\-uid\fP=\fI<num>\fP
.
Fake this unix uid; Real uid stays the same.
.TP
\fB-u\fP, \fB-\-username\fP=\fI<name>\fP
.
Use this extended username.
.TP
.B \ --fake-setuid
.
Track changes from setuid and setgid.
.TP
.B \ --valgrind
.
Enable valgrind support for Parrot.
.TP
.B \ -v
.
Display version number.
.TP
.B \ --is-running
.
Test is Parrot is already running.
.TP
\fB-w\fP, \fB-\-work-dir\fP=\fI<dir>\fP
.
Initial working directory.
.TP
.B \ -W
.
Display table of system calls trapped.
.TP
.B \ -Y
.
Force synchronous disk writes.
.TP
.B \ -Z
.
Enable automatic decompression on .gz files.
.TP
.BI \ --disable-service \ <service>
.
 Disable a compiled-in service (e.g. http, cvmfs, etc.)


.SH ENVIRONMENT VARIABLES
.LP
\FCparrot_run\FT sets the environment variable \FCPARROT_ENABLED\FT to the value \FC1\FT
for its child processes.  This makes it possible to set a visible flag in your shell prompt
when \FCparrot_run\FT is enabled.

.SH EXIT STATUS
.LP
\FCparrot_run\FT returns the exit status of the process that it runs.
If \FCparrot_run\FT is unable to start the process, it will return non-zero.

.SH EXAMPLES
.LP
To access a single remote file using \FCvi\FT:
.fam C
.nf
.nh
.IP "" 8
% parrot_run vi /anonftp/ftp.gnu.org/pub/README
.fi
.hy
.fam
.P

You can also run an entire shell inside of Parrot, like this:
.fam C
.nf
.nh
.IP "" 8
% parrot_run bash
% cd /anonftp/ftp.gnu.org/pub
% ls -la
% cat README
% exit
.fi
.hy
.fam
.P

To see the list of available Chirp servers around the world:
.fam C
.nf
.nh
.IP "" 8
% parrot_run ls -la /chirp
.fi
.hy
.fam
.P

Parrot can record the names of all the accessed files and the environment variables during the execution process of one program, like this:
.fam C
.nf
.nh
.IP "" 8
% parrot_run --name-list list.txt --env-list envlist ls ~
.fi
.hy
.fam
.P
The environment variables at the starting moment of your program will be recorded into \fBenvlist\fP. The absolute paths of all the accessed files, together with the system call types, will be recorded into \fBlist.txt\fP. For example, the file \fB/usr/bin/ls\fP is accessed using the \fBstat\fP system call, like this:
.fam C
.nf
.nh
.IP "" 8
% /usr/bin/ls|stat
.fi
.hy
.fam
.P

.SH NOTES ON DOCKER
.LP

Docker by default blocks ptrace, the system call on which parrot relies. To
run parrot inside docker, the container needs to be started using the
\FC--security-opt seccomp=unconfined\FT command line argument. For
example:

.fam C
.nf
.nh
.IP "" 8
    docker run --security-opt seccomp=unconfined MY-DOCKER-IMAGE
.fi
.hy
.fam
.P

.SH COPYRIGHT
.LP

The Cooperative Computing Tools are Copyright (C) 2005-2019 The University of Notre Dame.  This software is distributed under the GNU General Public License.  See the file COPYING for details.

.SH SEE ALSO
.LP


.IP \(bu 4
\fBCooperative Computing Tools Documentation\fP
.IP \(bu 4
\fBParrot User Manual\fP
.IP \(bu 4
\fBparrot_run(1)\fP \fBparrot_cp(1)\fP \fBparrot_getacl(1)\fP  \fBparrot_setacl(1)\fP  \fBparrot_mkalloc(1)\fP  \fBparrot_lsalloc(1)\fP  \fBparrot_locate(1)\fP  \fBparrot_timeout(1)\fP  \fBparrot_whoami(1)\fP  \fBparrot_mount(1)\fP  \fBparrot_md5(1)\fP  \fBparrot_package_create(1)\fP  \fBparrot_package_run(1)\fP  \fBchroot_package_run(1)\fP