bcc-execsnoop(8)

1execsnoop(8)                System Manager's Manual               execsnoop(8)
2
3
4

NAME

6       execsnoop  -  Trace  new  processes  via  exec()  syscalls.  Uses Linux
7       eBPF/bcc.
8

SYNOPSIS

10       execsnoop [-h] [-T] [-t] [-x] [--cgroupmap CGROUPMAP] [--mntnsmap  MAP‐
11       PATH] [-u USER] [-q] [-n NAME] [-l LINE] [-U] [--max-args MAX_ARGS]
12

DESCRIPTION

14       execsnoop traces new processes, showing the filename executed and argu‐
15       ment list.
16
17       It works by traces the execve() system call (commonly used exec() vari‐
18       ant).   This catches new processes that follow the fork->exec sequence,
19       as well as  processes  that  re-exec()  themselves.  Some  applications
20       fork()  but do not exec(), eg, for worker processes, which won't be in‐
21       cluded in the execsnoop output.
22
23       This works by tracing the kernel sys_execve()  function  using  dynamic
24       tracing, and will need updating to match any changes to this function.
25
26       Since this uses BPF, only the root user can use this tool.
27

REQUIREMENTS

29       CONFIG_BPF and bcc.
30

OPTIONS

32       -h     Print usage message.
33
34       -T     Include a time column (HH:MM:SS).
35
36       -U     Include UID column.
37
38       -t     Include a timestamp column.
39
40       -u USER
41              Filter by UID (or username)
42
43       -x     Include failed exec()s
44
45       -q     Add  "quotemarks"  around  arguments. Escape quotemarks in argu‐
46              ments with a backslash. For tracing empty arguments or arguments
47              that contain whitespace.
48
49       -n NAME
50              Only print command lines matching this name (regex)
51
52       -l LINE
53              Only print commands where arg contains this line (regex)
54
55       --max-args MAXARGS
56              Maximum number of arguments parsed and displayed, defaults to 20
57
58       --cgroupmap MAPPATH
59              Trace cgroups in this BPF map only (filtered in-kernel).
60
61       --mntnsmap  MAPPATH
62              Trace  mount  namespaces  in this BPF map only (filtered in-ker‐
63              nel).
64
65       -P PPID
66              Trace this parent PID only.
67
68
69       EXAMPLES
70
71       Trace all exec() syscalls:
72              # execsnoop
73
74       Trace all exec() syscalls, and include timestamps:
75              # execsnoop -t
76
77       Display process UID:
78              # execsnoop -U
79
80       Trace only UID 1000:
81              # execsnoop -u 1000
82
83       Trace only processes launched by root and display UID column:
84              # execsnoop -Uu root
85
86       Include failed exec()s:
87              # execsnoop -x
88
89       Put quotemarks around arguments.
90              # execsnoop -q
91
92       Only trace exec()s where the filename contains "mount":
93              # execsnoop -n mount
94
95       Only trace exec()s where argument's line contains "testpkg":
96              # execsnoop -l testpkg
97
98       Trace a set of cgroups only (see special_filtering.md from bcc  sources
99       for more details):
100              # execsnoop --cgroupmap /sys/fs/bpf/test01
101

FIELDS

103       TIME   Time of exec() return, in HH:MM:SS format.
104
105       TIME(s)
106              Time of exec() return, in seconds.
107
108       UID    User ID
109
110       PCOMM  Parent process/command name.
111
112       PID    Process ID
113
114       PPID   Parent process ID
115
116       RET    Return  value  of exec(). 0 == successs. Failures are only shown
117              when using the -x option.
118
119       ARGS   Filename for the exec(), followed be up to 19 arguments. An  el‐
120              lipsis  "..." is shown if the argument list is known to be trun‐
121              cated.
122

OVERHEAD

124       This traces the kernel execve  function  and  prints  output  for  each
125       event.  As the rate of this is generally expected to be low (< 1000/s),
126       the overhead is also expected to be negligible. If you have an applica‐
127       tion  that  is calling a high rate of exec()s, then test and understand
128       overhead before use.
129

SOURCE

131       This is from bcc.
132
133              https://github.com/iovisor/bcc
134
135       Also look in the bcc distribution for a  companion  _examples.txt  file
136       containing example usage, output, and commentary for this tool.
137

OS

139       Linux
140

STABILITY

142       Unstable - in development.
143

AUTHOR

145       Brendan Gregg, Rocky Xing
146