github.com/meulengracht/snapd@v0.0.0-20210719210640-8bde69bcc84e/cmd/snap-confine/snap-confine.rst (about)

     1  ==============
     2   snap-confine
     3  ==============
     4  
     5  -----------------------------------------------
     6  internal tool for confining snappy applications
     7  -----------------------------------------------
     8  
     9  :Author: zygmunt.krynicki@canonical.com
    10  :Date:   2017-09-18
    11  :Copyright: Canonical Ltd.
    12  :Version: 2.28
    13  :Manual section: 8
    14  :Manual group: snappy
    15  
    16  SYNOPSIS
    17  ========
    18  
    19  	snap-confine [--classic] [--base BASE] SECURITY_TAG COMMAND [...ARGUMENTS]
    20  
    21  DESCRIPTION
    22  ===========
    23  
    24  The `snap-confine` is a program used internally by `snapd` to construct the
    25  execution environment for snap applications.
    26  
    27  OPTIONS
    28  =======
    29  
    30  The `snap-confine` program accepts two options:
    31  
    32      `--classic` requests the so-called _classic_ _confinement_ in which
    33      applications are not confined at all (like in classic systems, hence the
    34      name). This disables the use of a dedicated, per-snap mount namespace. The
    35      `snapd` service generates permissive apparmor and seccomp profiles that
    36      allow everything.
    37  
    38      `--base BASE` directs snap-confine to use the given base snap as the root
    39      filesystem. If omitted it defaults to the `core` snap. This is derived from
    40      snap meta-data by `snapd` when starting the application process.
    41  
    42  FEATURES
    43  ========
    44  
    45  Apparmor profiles
    46  -----------------
    47  
    48  `snap-confine` switches to the apparmor profile `$SECURITY_TAG`. The profile is
    49  **mandatory** and `snap-confine` will refuse to run without it.
    50  
    51  The profile has to be loaded into the kernel prior to using `snap-confine`.
    52  Typically this is arranged for by `snapd`. The profile contains rich
    53  description of what the application process is allowed to do, this includes
    54  system calls, file paths, access patterns, linux capabilities, etc. The
    55  apparmor profile can also do extensive dbus mediation. Refer to apparmor
    56  documentation for more details.
    57  
    58  Seccomp profiles
    59  ----------------
    60  
    61  `snap-confine` looks for the
    62  `/var/lib/snapd/seccomp/bpf/$SECURITY_TAG.bin` file. This file is
    63  **mandatory** and `snap-confine` will refuse to run without it. This
    64  file contains the seccomp bpf binary program that is loaded into the
    65  kernel by snap-confine.
    66  
    67  The file is generated with the `/usr/lib/snapd/snap-seccomp` compiler from the
    68  `$SECURITY_TAG.src` file that uses a custom syntax that describes the set of
    69  allowed system calls and optionally their arguments. The profile is then used
    70  to confine the started application.
    71  
    72  As a security precaution disallowed system calls cause the started application
    73  executable to be killed by the kernel. In the future this restriction may be
    74  lifted to return `EPERM` instead.
    75  
    76  Mount profiles
    77  --------------
    78  
    79  `snap-confine` uses a helper process, `snap-update-ns`, to apply the mount
    80  namespace profile to freshly constructed mount namespace. That tool looks for
    81  the `/var/lib/snapd/mount/snap.$SNAP_NAME.fstab` file.  If present it is read,
    82  parsed and treated like a mostly-typical `fstab(5)` file.  The mount directives
    83  listed there are executed in order. All directives must succeed as any failure
    84  will abort execution.
    85  
    86  By default all mount entries start with the following flags: `bind`, `ro`,
    87  `nodev`, `nosuid`.  Some of those flags can be reversed by an appropriate
    88  option (e.g. `rw` can cause the mount point to be writable).
    89  
    90  Certain additional features are enabled and conveyed through the use of mount
    91  options prefixed with `x-snapd-`.
    92  
    93  As a security precaution only `bind` mounts are supported at this time.
    94  
    95  Sharing of the mount namespace
    96  ------------------------------
    97  
    98  As of version 1.0.41 all the applications from the same snap will share the
    99  same mount namespace. Applications from different snaps continue to use
   100  separate mount namespaces.
   101  
   102  ENVIRONMENT
   103  ===========
   104  
   105  `snap-confine` responds to the following environment variables
   106  
   107  `SNAP_CONFINE_DEBUG`:
   108  	When defined the program will print additional diagnostic information about
   109  	the actions being performed. All the output goes to stderr.
   110  
   111  The following variables are only used when `snap-confine` is not setuid root.
   112  This is only applicable when testing the program itself.
   113  
   114  `SNAPPY_LAUNCHER_INSIDE_TESTS`:
   115  	Internal variable that should not be relied upon.
   116  
   117  `SNAPPY_LAUNCHER_SECCOMP_PROFILE_DIR`:
   118  	Internal variable that should not be relied upon.
   119  
   120  `SNAP_USER_DATA`:
   121      Full path to the directory like /home/$LOGNAME/snap/$SNAP_NAME/$SNAP_REVISION.
   122  
   123      This directory is created by snap-confine on startup. This is a temporary
   124      feature that will be merged into snapd's snap-run command. The set of directories
   125      that can be created is confined with apparmor.
   126  
   127  FILES
   128  =====
   129  
   130  `snap-confine` and `snap-update-ns` use the following files:
   131  
   132  `/var/lib/snapd/mount/snap.*.fstab`:
   133  
   134  	Description of the mount profile.
   135  
   136  `/var/lib/snapd/seccomp/bpf/*.src`:
   137  
   138  	Input for the /usr/lib/snapd/snap-seccomp profile compiler.
   139  
   140  `/var/lib/snapd/seccomp/bpf/*.bin`:
   141  
   142  	Compiled seccomp bpf profile programs.
   143  
   144  `/run/snapd/ns/`:
   145  
   146      Directory used to keep shared mount namespaces.
   147  
   148      `snap-confine` internally converts this directory to a private bind mount.
   149      Semantically the behavior is identical to the following mount commands:
   150  
   151      mount --bind /run/snapd/ns /run/snapd/ns
   152      mount --make-private /run/snapd/ns
   153  
   154  `/run/snapd/ns/.lock`:
   155  
   156      A `flock(2)`-based lock file acquired to create and convert
   157      `/run/snapd/ns/` to a private bind mount.
   158  
   159  `/run/snapd/ns/$SNAP_NAME.lock`:
   160  
   161      A `flock(2)`-based lock file acquired to create or join the mount namespace
   162      represented as `/run/snaps/ns/$SNAP_NAME.mnt`.
   163  
   164  `/run/snapd/ns/$SNAP_NAME.mnt`:
   165  
   166      This file can be either:
   167  
   168      - An empty file that may be seen before the mount namespace is preserved or
   169        when the mount namespace is unmounted.
   170      - A file belonging to the `nsfs` file system, representing a fully
   171        populated mount namespace of a given snap. The file is bind mounted from
   172        `/proc/self/ns/mnt` from the first process in any snap.
   173  
   174  `/proc/self/mountinfo`:
   175  
   176      This file is read to decide if `/run/snapd/ns/` needs to be created and
   177      converted to a private bind mount, as described above.
   178  
   179  Note that the apparmor profile is external to `snap-confine` and is loaded
   180  directly into the kernel. The actual apparmor profile is managed by `snapd`.
   181  
   182  BUGS
   183  ====
   184  
   185  Please report all bugs with https://bugs.launchpad.net/snap-confine/+filebug