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
21       included 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
66       EXAMPLES
67
68       Trace all exec() syscalls:
69              # execsnoop
70
71       Trace all exec() syscalls, and include timestamps:
72              # execsnoop -t
73
74       Display process UID:
75              # execsnoop -U
76
77       Trace only UID 1000:
78              # execsnoop -u 1000
79
80       Trace only processes launched by root and display UID column:
81              # execsnoop -Uu root
82
83       Include failed exec()s:
84              # execsnoop -x
85
86       Put quotemarks around arguments.
87              # execsnoop -q
88
89       Only trace exec()s where the filename contains "mount":
90              # execsnoop -n mount
91
92       Only trace exec()s where argument's line contains "testpkg":
93              # execsnoop -l testpkg
94
95       Trace a set of cgroups only (see special_filtering.md from bcc  sources
96       for more details):
97              # execsnoop --cgroupmap /sys/fs/bpf/test01
98

FIELDS

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

OVERHEAD

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

SOURCE

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

OS

136       Linux
137

STABILITY

139       Unstable - in development.
140

AUTHOR

142       Brendan Gregg
143