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

     1  /*
     2   * Copyright (C) 2016 Canonical Ltd
     3   *
     4   * This program is free software: you can redistribute it and/or modify
     5   * it under the terms of the GNU General Public License version 3 as
     6   * published by the Free Software Foundation.
     7   *
     8   * This program is distributed in the hope that it will be useful,
     9   * but WITHOUT ANY WARRANTY; without even the implied warranty of
    10   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    11   * GNU General Public License for more details.
    12   *
    13   * You should have received a copy of the GNU General Public License
    14   * along with this program.  If not, see <http://www.gnu.org/licenses/>.
    15   *
    16   */
    17  
    18  #ifndef SNAP_NAMESPACE_SUPPORT
    19  #define SNAP_NAMESPACE_SUPPORT
    20  
    21  #include <stdbool.h>
    22  
    23  #include "../libsnap-confine-private/apparmor-support.h"
    24  #include "snap-confine-invocation.h"
    25  
    26  /**
    27   * Re-associate the current process with the mount namespace of pid 1.
    28   *
    29   * This function inspects the mount namespace of the current process and that
    30   * of pid 1. In case they differ the current process is re-associated with the
    31   * mount namespace of pid 1.
    32   *
    33   * This function should be called before sc_initialize_mount_ns().
    34   **/
    35  void sc_reassociate_with_pid1_mount_ns(void);
    36  
    37  /**
    38   * Initialize namespace sharing.
    39   *
    40   * This function must be called once in each process that wishes to create or
    41   * join a namespace group.
    42   *
    43   * It is responsible for bind mounting the control directory over itself and
    44   * making it private (unsharing it with all the other peers) so that it can be
    45   * used for storing preserved namespaces as bind-mounted files from the nsfs
    46   * filesystem (namespace filesystem).
    47   *
    48   * This function should be called with a global lock (see sc_lock_global) held
    49   * to ensure that no other instance of snap-confine attempts to do this
    50   * concurrently.
    51   *
    52   * This function inspects /proc/self/mountinfo to determine if the directory
    53   * where namespaces are kept (/run/snapd/ns) is correctly prepared as described
    54   * above.
    55   *
    56   * Experimental features can be enabled via optional feature flags.
    57   *
    58   * For more details see namespaces(7).
    59   **/
    60  void sc_initialize_mount_ns(unsigned int experimental_features);
    61  
    62  /**
    63   * Data required to manage namespaces amongst a group of processes.
    64   */
    65  struct sc_mount_ns;
    66  
    67  /**
    68   * Open a namespace group.
    69   *
    70   * This will open and keep file descriptors for /run/snapd/ns/.
    71   *
    72   * The following methods should be called only while holding a lock protecting
    73   * that specific snap namespace:
    74   * - sc_create_or_join_mount_ns()
    75   * - sc_preserve_populated_mount_ns()
    76   */
    77  struct sc_mount_ns *sc_open_mount_ns(const char *group_name);
    78  
    79  /**
    80   * Close namespace group.
    81   *
    82   * This will close all of the open file descriptors and release allocated memory.
    83   */
    84  void sc_close_mount_ns(struct sc_mount_ns *group);
    85  
    86  /**
    87   * Join a preserved mount namespace if one exists.
    88   *
    89   * Technically the function opens /run/snapd/ns/${group_name}.mnt and tries to
    90   * use setns() with the obtained file descriptor.
    91   *
    92   * If the preserved mount namespace does not exist or exists but is stale and
    93   * was discarded and returns ESRCH. If the mount namespace was joined the
    94   * function returns zero.
    95   **/
    96  int sc_join_preserved_ns(struct sc_mount_ns *group, struct sc_apparmor
    97  			 *apparmor, const sc_invocation * inv,
    98  			 int snap_discard_ns_fd);
    99  
   100  /**
   101   * Join a preserved, per-user, mount namespace if one exists.
   102   *
   103   * Technically the function opens /run/snapd/ns/snap.$SNAP_NAME.$UID.mnt and
   104   * tries to use setns() with the obtained file descriptor.
   105   *
   106   * The return is ESRCH if a preserved per-user mount namespace does not exist
   107   * and cannot be joined or zero otherwise.
   108  **/
   109  int sc_join_preserved_per_user_ns(struct sc_mount_ns *group,
   110  				  const char *snap_name);
   111  
   112  /**
   113   * Fork off a helper process for mount namespace capture.
   114   *
   115   * This function forks the helper process. It needs to be paired with
   116   * sc_wait_for_helper which instructs the helper to shut down and waits for
   117   * that to happen.
   118   *
   119   * For rationale for forking and using a helper process please see
   120   * https://lists.linuxfoundation.org/pipermail/containers/2013-August/033386.html
   121   **/
   122  void sc_fork_helper(struct sc_mount_ns *group, struct sc_apparmor *apparmor);
   123  
   124  /**
   125   * Preserve prepared namespace group.
   126   *
   127   * This function signals the child support process for namespace capture to
   128   * perform the capture.
   129   *
   130   * Technically this function writes to pipe that causes the child process to
   131   * wake up and bind mount /proc/$ppid/ns/mnt to
   132   * /run/snapd/ns/${group_name}.mnt.
   133   *
   134   * The helper process will wait for subsequent commands. Please call
   135   * sc_wait_for_helper() to terminate it.
   136   **/
   137  void sc_preserve_populated_mount_ns(struct sc_mount_ns *group);
   138  
   139  void sc_preserve_populated_per_user_mount_ns(struct sc_mount_ns *group);
   140  
   141  /**
   142   * Ask the helper process to terminate and wait for it to finish.
   143   *
   144   * This function asks the helper process to exit by writing an appropriate
   145   * command to the pipe used for the inter process communication between the
   146   * main snap-confine process and the helper and then waits for the process to
   147   * terminate cleanly.
   148   **/
   149  void sc_wait_for_helper(struct sc_mount_ns *group);
   150  
   151  void sc_store_ns_info(const sc_invocation * inv);
   152  
   153  #endif