gvisor.dev/gvisor@v0.0.0-20240520182842-f9d4d51c7e0f/g3doc/user_guide/FAQ.md (about)

     1  # FAQ
     2  
     3  [TOC]
     4  
     5  ### What operating systems are supported? {#supported-os}
     6  
     7  Today, gVisor requires Linux.
     8  
     9  ### What CPU architectures are supported? {#supported-cpus}
    10  
    11  gVisor currently supports [x86_64/AMD64](https://en.wikipedia.org/wiki/X86-64)
    12  compatible processors. Preliminary support is also available for
    13  [ARM64](https://en.wikipedia.org/wiki/ARM_architecture#AArch64).
    14  
    15  ### Do I need to modify my Linux application to use gVisor? {#modify-app}
    16  
    17  No. gVisor is capable of running unmodified Linux binaries.
    18  
    19  ### What binary formats does gVisor support? {#supported-binaries}
    20  
    21  gVisor supports Linux
    22  [ELF](https://en.wikipedia.org/wiki/Executable_and_Linkable_Format) binaries.
    23  
    24  Binaries run in gVisor should be built for the
    25  [AMD64](https://en.wikipedia.org/wiki/X86-64) or
    26  [AArch64](https://en.wikipedia.org/wiki/ARM_architecture#AArch64) CPU
    27  architectures.
    28  
    29  ### Can I run Docker images using gVisor? {#docker-images}
    30  
    31  Yes. Please see the [Docker Quick Start][docker].
    32  
    33  ### Can I run Kubernetes pods using gVisor? {#k8s-pods}
    34  
    35  Yes. Please see the [Kubernetes Quick Start][k8s].
    36  
    37  ### How do I integrate gVisor in my existing production stack? {#productionize}
    38  
    39  See the [Production guide].
    40  
    41  ### What's the security model? {#security-model}
    42  
    43  See the [Security Model][security-model].
    44  
    45  ## Troubleshooting
    46  
    47  ### My container runs fine with `runc` but fails with `runsc` {#app-compatibility}
    48  
    49  If you’re having problems running a container with `runsc` it’s most likely due
    50  to a compatibility issue or a missing feature in gVisor. See
    51  [Debugging][debugging].
    52  
    53  ### When I run my container, docker fails with: `open /run/containerd/.../<containerid>/log.json: no such file or directory` {#memfd-create}
    54  
    55  You are using an older version of Linux which doesn't support `memfd_create`.
    56  
    57  This is tracked in [bug #268](https://gvisor.dev/issue/268).
    58  
    59  ### When I run my container, docker fails with: `flag provided but not defined: -console` {#old-docker}
    60  
    61  You're using an old version of Docker. See [Docker Quick Start][docker].
    62  
    63  ### I can’t see a file copied with: `docker cp` {#fs-cache}
    64  
    65  For performance reasons, gVisor caches directory contents, and therefore it may
    66  not realize a new file was copied to a given directory. To invalidate the cache
    67  and force a refresh, create a file under the directory in question and list the
    68  contents again.
    69  
    70  As a workaround, shared root filesystem can be enabled. See
    71  [Filesystem][filesystem].
    72  
    73  This bug is tracked in [bug #4](https://gvisor.dev/issue/4).
    74  
    75  Note that `kubectl cp` works because it does the copy by exec'ing inside the
    76  sandbox, and thus gVisor's internal cache is made aware of the new files and
    77  directories.
    78  
    79  ### I'm getting an error like: `panic: unable to attach: operation not permitted` or `fork/exec /proc/self/exe: invalid argument: unknown` {#runsc-perms}
    80  
    81  Make sure that permissions is correct on the `runsc` binary.
    82  
    83  ```bash
    84  sudo chmod a+rx /usr/local/bin/runsc
    85  ```
    86  
    87  If your Kernel is configured with YAMA LSM (see
    88  https://www.kernel.org/doc/Documentation/security/Yama.txt and
    89  https://man7.org/linux/man-pages/man2/ptrace.2.html) gVisor may fail in certain
    90  modes (i.e., systrap and/or directfs) with this error if
    91  `/proc/sys/kernel/yama/ptrace_scope` is set to 2. If this is the case, try
    92  setting `/proc/sys/kernel/yama/ptrace_scope` to max of mode 1:
    93  
    94  ```bash
    95  sudo cat /proc/sys/kernel/yama/ptrace_scope
    96  2
    97  sudo bash -c 'echo 1 > /proc/sys/kernel/yama/ptrace_scope'
    98  ```
    99  
   100  ### I'm getting an error like `mount submount "/etc/hostname": creating mount with source ".../hostname": input/output error: unknown.` {#memlock}
   101  
   102  There is a bug in Linux kernel versions 5.1 to 5.3.15, 5.4.2, and 5.5. Upgrade
   103  to a newer kernel or add the following to
   104  `/lib/systemd/system/containerd.service` as a workaround.
   105  
   106  ```
   107  LimitMEMLOCK=infinity
   108  ```
   109  
   110  And run `systemctl daemon-reload && systemctl restart containerd` to restart
   111  containerd.
   112  
   113  See [issue #1765](https://gvisor.dev/issue/1765) for more details.
   114  
   115  ### I'm getting an error like `RuntimeHandler "runsc" not supported` {#runtime-handler}
   116  
   117  This error indicates that the Kubernetes CRI runtime was not set up to handle
   118  `runsc` as a runtime handler. Please ensure that containerd configuration has
   119  been created properly and containerd has been restarted. See the
   120  [containerd quick start](containerd/quick_start.md) for more details.
   121  
   122  If you have ensured that containerd has been set up properly and you used
   123  kubeadm to create your cluster please check if Docker is also installed on that
   124  system. Kubeadm prefers using Docker if both Docker and containerd are
   125  installed.
   126  
   127  Please recreate your cluster and set the `--cri-socket` option on kubeadm
   128  commands. For example:
   129  
   130  ```bash
   131  kubeadm init --cri-socket=/var/run/containerd/containerd.sock ...
   132  ```
   133  
   134  To fix an existing cluster edit the `/var/lib/kubelet/kubeadm-flags.env` file
   135  and set the `--container-runtime` flag to `remote` and set the
   136  `--container-runtime-endpoint` flag to point to the containerd socket. e.g.
   137  `/var/run/containerd/containerd.sock`.
   138  
   139  ### My container cannot resolve another container's name when using Docker user defined bridge {#docker-bridge}
   140  
   141  This is normally indicated by errors like `bad address 'container-name'` when
   142  trying to communicate to another container in the same network.
   143  
   144  Docker user defined bridge uses an embedded DNS server bound to the loopback
   145  interface on address 127.0.0.10. This requires access to the host network in
   146  order to communicate to the DNS server. runsc network is isolated from the host
   147  and cannot access the DNS server on the host network without breaking the
   148  sandbox isolation. There are a few different workarounds you can try:
   149  
   150  *   Use default bridge network with `--link` to connect containers. Default
   151      bridge doesn't use embedded DNS.
   152  *   Use [`--network=host`][host-net] option in runsc, however beware that it
   153      will use the host network stack and is less secure.
   154  *   Use IPs instead of container names.
   155  *   Use [Kubernetes][k8s]. Container name lookup works fine in Kubernetes.
   156  
   157  ### I'm getting an error like `dial unix /run/containerd/s/09e4...8cff: connect: connection refused: unknown` {#shim-connect}
   158  
   159  This error may happen when using `gvisor-containerd-shim` with a `containerd`
   160  that does not contain the fix for [CVE-2020-15257]. The resolve the issue,
   161  update containerd to 1.3.9 or 1.4.3 (or newer versions respectively).
   162  
   163  [security-model]: /docs/architecture_guide/security/
   164  [host-net]: /docs/user_guide/networking/#network-passthrough
   165  [debugging]: /docs/user_guide/debugging/
   166  [filesystem]: /docs/user_guide/filesystem/
   167  [docker]: /docs/user_guide/quick_start/docker/
   168  [k8s]: /docs/user_guide/quick_start/kubernetes/
   169  [Production guide]: /docs/user_guide/production/
   170  [CVE-2020-15257]: https://github.com/containerd/containerd/security/advisories/GHSA-36xw-fx78-c5r4