seccomp_init(3)

1seccomp_init(3)            libseccomp Documentation            seccomp_init(3)
2
3
4

NAME

6       seccomp_init, seccomp_reset - Initialize the seccomp filter state
7

SYNOPSIS

9       #include <seccomp.h>
10
11       typedef void * scmp_filter_ctx;
12
13       scmp_filter_ctx seccomp_init(uint32_t def_action);
14       int seccomp_reset(scmp_filter_ctx ctx, uint32_t def_action);
15
16       Link with -lseccomp.
17

DESCRIPTION

19       The seccomp_init() and seccomp_reset() functions (re)initialize the in‐
20       ternal seccomp filter state, prepares it for use, and sets the  default
21       action  based on the def_action parameter.  The seccomp_init() function
22       must be called before any other libseccomp functions as the rest of the
23       library  API  will  fail if the filter context is not initialized prop‐
24       erly.  The seccomp_reset() function releases the existing  filter  con‐
25       text state before reinitializing it and can only be called after a call
26       to seccomp_init() has succeeded.  If seccomp_reset() is called  with  a
27       NULL  filter,  it resets the library's global task state, including any
28       notification file descriptors retrieved by seccomp_notify_fd(3).   Nor‐
29       mally  this is not needed, but it may be required to continue using the
30       library after a fork() or clone() call to ensure the API level and user
31       notification state is properly reset.
32
33       When  the  caller  is  finished  configuring the seccomp filter and has
34       loaded it into the kernel, the caller should call seccomp_release(3) to
35       release all of the filter context state.
36
37       Valid def_action values are as follows:
38
39       SCMP_ACT_KILL
40              The  thread will be terminated by the kernel with SIGSYS when it
41              calls a syscall that does not match any of the  configured  sec‐
42              comp  filter  rules.   The  thread will not be able to catch the
43              signal.
44
45       SCMP_ACT_KILL_PROCESS
46              The entire process will be terminated by the kernel with  SIGSYS
47              when  it  calls a syscall that does not match any of the config‐
48              ured seccomp filter rules.
49
50       SCMP_ACT_TRAP
51              The thread will be sent a SIGSYS signal when it calls a  syscall
52              that  does not match any of the configured seccomp filter rules.
53              It may catch this and change its behavior accordingly.  When us‐
54              ing  SA_SIGINFO  with  sigaction(2),  si_code  will  be  set  to
55              SYS_SECCOMP, si_syscall will be set to the syscall  that  failed
56              the rules, and si_arch will be set to the AUDIT_ARCH for the ac‐
57              tive ABI.
58
59       SCMP_ACT_ERRNO(uint16_t errno)
60              The thread will receive a return value of errno when it calls  a
61              syscall that does not match any of the configured seccomp filter
62              rules.
63
64       SCMP_ACT_TRACE(uint16_t msg_num)
65              If the thread is being traced and the tracing process  specified
66              the  PTRACE_O_TRACESECCOMP  option in the call to ptrace(2), the
67              tracing process will be notified, via PTRACE_EVENT_SECCOMP,  and
68              the  value  provided  in  msg_num  can  be  retrieved  using the
69              PTRACE_GETEVENTMSG option.
70
71       SCMP_ACT_LOG
72              The seccomp filter will have no effect on the thread calling the
73              syscall  if it does not match any of the configured seccomp fil‐
74              ter rules but the syscall will be logged.
75
76       SCMP_ACT_ALLOW
77              The seccomp filter will have no effect on the thread calling the
78              syscall  if it does not match any of the configured seccomp fil‐
79              ter rules.
80

RETURN VALUE

82       The seccomp_init() function returns a filter context on  success,  NULL
83       on  failure.   The  seccomp_reset() function returns zero on success or
84       one of the following error codes on failure:
85
86       -EINVAL
87              Invalid input, either the context or action is invalid.
88
89       -ENOMEM
90              The library was unable to allocate enough memory.
91

EXAMPLES

93       #include <seccomp.h>
94
95       int main(int argc, char *argv[])
96       {
97            int rc = -1;
98            scmp_filter_ctx ctx;
99
100            ctx = seccomp_init(SCMP_ACT_KILL);
101            if (ctx == NULL)
102                 goto out;
103
104            /* ... */
105
106            rc = seccomp_reset(ctx, SCMP_ACT_KILL);
107            if (rc < 0)
108                 goto out;
109
110            /* ... */
111
112       out:
113            seccomp_release(ctx);
114            return -rc;
115       }
116

NOTES

118       While the seccomp filter can be generated independent  of  the  kernel,
119       kernel  support is required to load and enforce the seccomp filter gen‐
120       erated by libseccomp.
121
122       The libseccomp project site, with more information and the source  code
123       repository,  can  be  found  at  https://github.com/seccomp/libseccomp.
124       This tool, as well as the libseccomp library, is currently under devel‐
125       opment,  please  report any bugs at the project site or directly to the
126       author.
127

AUTHOR

129       Paul Moore <paul@paul-moore.com>
130