auditctl



AUDITCTL:(8)            System Administration Utilities           AUDITCTL:(8)




NAME

       auditctl - a utility to assist controlling the kernel’s audit system


SYNOPSIS

       auditctl [options]


DESCRIPTION

       The  auditctl  program is used to control the behavior, get status, and
       add or delete rules into the 2.6 kernel’s audit system.


OPTIONS

       -b <backlog>
              Set max number of  outstanding  audit  buffers  allowed  (Kernel
              Default=64)  If  all  buffers are full, the failure flag is con-
              sulted by the kernel for action.

       -e [0|1]
              Set enabled flag. This can be used to temporarily disable audit-
              ing or re-enable it.

       -f [0..2]
              Set failure flag 0=silent 1=printk 2=panic. This option lets you
              determine how you want the kernel  to  handle  critical  errors.
              Example conditions where this flag is consulted includes: trans-
              mission  errors  to  userspace  audit  daemon,   backlog   limit
              exceeded,  out  of  kernel  memory, and rate limit exceeded. The
              default value is 1. Secure environments will  probably  want  to
              set this to 2.

       -h     Help

       -i     Ignore errors when reading rules from a file

       -l     List all rules 1 per line.

       -k <key>
              Set  a  filter  key  on  a filesystem watch. The filterkey is an
              arbitrary string of text that can be up to 31 bytes long. It can
              uniquely identify the audit records produced by the watch.

       -m text
              Send  a  user-space message into the audit system. This can only
              be done by the root user.

       -p [r|w|x|a]
              Set permissions filter for a file system watch. r=read, w=write,
              x=execute, a=append.

       -r <rate>
              Set  limit in messages/sec (0=none) If this rate is non-zero and
              is exceeded, the failure flag is consulted  by  the  kernel  for
              action. The default value is 0.

       -R <file>
              Read  rules from a file. The rules must be 1 per line and in the
              order that they are to be executed in. The  rule  file  must  be
              owned  by  root  and  not  readable by other users or it will be
              rejected. The rule file may have comments embedded  by  starting
              the line with a ’#’ character.

       -s     Report status

       -a <l,a>
              Append  rule to the end of <l>ist with <a>ction. Please note the
              comma separating the two values. Omitting it will cause  errors.
              The following describes the valid list names:

              task        Add  a  rule to the per task list. This rule list is
                          used only at the time a  task  is  created  --  when
                          fork()  or  clone()  are  called by the parent task.
                          When using this list, you  should  only  use  fields
                          that  are  known  at task creation time, such as the
                          uid, gid, etc.

              entry       Add a rule to the syscall entry list. This  list  is
                          used  upon entry to a system call to determine if an
                          audit event should be created.

              exit        Add a rule to the syscall exit list.  This  list  is
                          used upon exit from a system call to determine if an
                          audit event should be created.

              user        Add a rule to the user  message  filter  list.  This
                          list  is  used by the kernel to filter events origi-
                          nating in user space before  relaying  them  to  the
                          audit  daemon.  It  should  be  noted  that the only
                          fields that are valid are: uid, auid, gid, and  pid.
                          All other fileds will be treated as non-matching.

              watch       Add  a  rule  to  the file system watch filter list.
                          This list is used to filter  events  that  originate
                          from file system watches. You can use syscall match-
                          ing with this list, but the only syscalls  that  are
                          meaningful are I/O related.

       The following describes the valid actions for the rule:

              never       No audit records will be generated. This can be used
                          to suppress event generation. In general,  you  want
                          suppressions  at  the top of the list instead of the
                          bottom. This is because the event  triggers  on  the
                          first matching rule.

              possible    Allocate  an  audit  context  for  the new task, and
                          always fill it in at syscall entry time. This  makes
                          a  full  syscall record available if some other part
                          of the kernel decides it should  be  recorded.  This
                          option  is  intended for use with file system audit-
                          ing. For example, you could use this with  the  open
                          syscall  and  set a file system watch for a specific
                          file. In this case, you will not get an audit  event
                          for each call to open - just the ones that the files
                          system watch triggers on.

              always      Allocate an audit context,  always  fill  it  in  at
                          syscall entry time, and always write out a record at
                          syscall exit time.

       -A <l,a>
              Add rule to the beginning <l>ist with <a>ction

       -d <l,a>
              Delete rule from <l>ist with <a>ction. The rule is deleted  only
              if it exactly matches syscall name and field names.

       -D     Delete all rules and watches.

       -S [Syscall name or number|all]
              Any  syscall name or number may be used. The word ’all’ may also
              be used.  If this syscall is made by a program,  then  start  an
              audit  record. If a field rule is given and no syscall is speci-
              fied, it will default to all syscalls. You may also specify mul-
              tiple  syscalls  in the same rule. Doing so improves performance
              since fewer rules need to be evaluated.

       -F [n=v | n!=v]
              Build a rule field: name = value. You may have  multiple  fields
              passed  on  a command line. Each one must start with -F. You may
              have up to 64 fields passed on a single commandline. Each  field
              equation  is  anded  with each other to trigger an audit record.
              There are 2 operators supported - equal and  not  equal.  Fields
              that  take  a user ID may instead have the user’s name; the pro-
              gram will convert the name to user ID. The same is true of group
              names. Valid fields are:

              pid         Process ID

              uid         User ID

              euid        Effective User ID

              suid        Set User ID

              fsuid       Filesystem User ID

              gid         Group ID

              egid        Effect Group ID

              sgid        Set Group ID

              fsgid       Filesystem Group ID

              auid        The  original  ID  the  user  logged in with. Its an
                          abbreviation of audit uid.

              pers        OS Personality Number

              arch        The CPU architecture of the syscall. The arch can be
                          found  doing ’uname -m’. If you do not know the arch
                          of your machine but you  want  to  use  the  32  bit
                          syscall  table and your machine supports 32 bit, you
                          can also use b32 for the arch. The same  applies  to
                          the 64 bit syscall table, you can use b64.

              devmajor    Device Major Number

              devminor    Device Minor Number

              inode       Inode Number

              exit        Exit value from a syscall

              success     If the exit value is >= 0 this is true/yes otherwise
                          its false/no. When writing  a  rule,  use  a  1  for
                          true/yes and a 0 for false/no

              a0, a1, a2, a3
                          Respectively,  the  first  4 arguments to a syscall.
                          Note that string arguments are not  supported.  This
                          is  because  the  kernel  is passed a pointer to the
                          string. Triggering on a pointer address value is not
                          likely to work. So, when using this, you should only
                          use on numeric values. This is  most  likely  to  be
                          used on platforms that multiplex socket or ipc oper-
                          ations.

       -t <syscall>
              Translate syscall number to syscall name. No other task is  per-
              formed.  Also  note  that you can use the -F arch=xxx to set the
              syscall table for translation. If  you  use  this,  it  must  be
              before  the  -t  parameter  or the machine’s native type will be
              used.

       -w <path>
              Insert a watch for the file system object at <path>. You  cannot
              insert a watch to the top level directory. This is prohibited by
              the kernel. Wildcards are not supported either and will generate
              a  warning.  The  way that watches work is by tracking the inode
              internally. This means that if you put a watch on  a  directory,
              you  will  see  what appears to be file events, but it is really
              just the updating of meta data. You might miss a few  events  by
              doing  this.  If you need to watch all files in a directory, its
              recommended to place an individual watch on  each  file.  Unlike
              syscall  auditing rules, watches do not impact performance based
              on the number of rules sent to the kernel.

       -W <path>
              Remove a watch for the file system object at <path>


EXAMPLES

       To see all syscalls made by a program:

       auditctl -a entry,always -S all -F pid=1005

       To see files opened by a specific user:

       auditctl -a exit,always -S open -F auid=510

       To see unsuccessful open call’s:

       auditctl -a exit,always -S open -F success!=0



SEE ALSO

       auditd(8)



Red Hat                            Oct 2005                       AUDITCTL:(8)

Man(1) output converted with man2html