docs(troubleshooting): update on sandboxing (#3531)
This commit is contained in:
parent
eb7bd9d7d3
commit
766a9516b0
@ -49,10 +49,6 @@ lsb-release
|
|||||||
xdg-utils
|
xdg-utils
|
||||||
wget
|
wget
|
||||||
```
|
```
|
||||||
Also enable `kernel.unprivileged_userns_clone` for server `sysctl`. See [comment](https://github.com/GoogleChrome/puppeteer/issues/290#issuecomment-403876758)
|
|
||||||
```bash
|
|
||||||
sudo sysctl -w kernel.unprivileged_userns_clone=1
|
|
||||||
```
|
|
||||||
</details>
|
</details>
|
||||||
|
|
||||||
<details>
|
<details>
|
||||||
@ -88,33 +84,97 @@ xorg-x11-fonts-misc
|
|||||||
- [#391](https://github.com/GoogleChrome/puppeteer/issues/391) - CentOS troubleshooting
|
- [#391](https://github.com/GoogleChrome/puppeteer/issues/391) - CentOS troubleshooting
|
||||||
- [#379](https://github.com/GoogleChrome/puppeteer/issues/379) - Alpine troubleshooting
|
- [#379](https://github.com/GoogleChrome/puppeteer/issues/379) - Alpine troubleshooting
|
||||||
|
|
||||||
## Chrome Headless fails due to sandbox issues
|
## Setting Up Chrome Linux Sandbox
|
||||||
|
|
||||||
- Make sure kernel version is up-to-date.
|
In order to protect the host environment from untrusted web content, Chrome uses [multiple layers of sandboxing](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/linux_sandboxing.md). For this to work properly,
|
||||||
- Read about linux sandbox here: https://chromium.googlesource.com/chromium/src/+/master/docs/linux_suid_sandbox_development.md
|
the host should be configured first. If there's no good sandbox for Chrome to use, it will crash
|
||||||
- Try running without the sandbox (**Note: running without the sandbox is not recommended due to security reasons!**)
|
with the error `No usable sandbox!`.
|
||||||
|
|
||||||
|
If you **absolutely trust** the content you open in Chrome, you can launch Chrome
|
||||||
|
with the `--no-sandbox` argument:
|
||||||
|
|
||||||
```js
|
```js
|
||||||
const browser = await puppeteer.launch({args: ['--no-sandbox', '--disable-setuid-sandbox']});
|
const browser = await puppeteer.launch({args: ['--no-sandbox', '--disable-setuid-sandbox']});
|
||||||
```
|
```
|
||||||
|
|
||||||
|
> **NOTE**: Running without a sandbox is **strongly discouraged**. Consider configuring a sandbox instead.
|
||||||
|
|
||||||
|
There are 2 ways to configure a sandbox in Chromium.
|
||||||
|
|
||||||
|
### [recommended] Enable [user namespace cloning](http://man7.org/linux/man-pages/man7/user_namespaces.7.html)
|
||||||
|
|
||||||
|
User namespace cloning is only supported by modern kernels. Unprivileged user namespaces are generally fine to enable,
|
||||||
|
but in some cases they open up more kernel attack surface for (unsandboxed) non-root processes to elevate to
|
||||||
|
kernel privileges.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sudo sysctl -w kernel.unprivileged_userns_clone=1
|
||||||
|
```
|
||||||
|
|
||||||
|
### [alternative] Setup [setuid sandbox](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/linux_suid_sandbox_development.md)
|
||||||
|
|
||||||
|
The setuid sandbox comes as a standalone executable and is located next to the Chromium that Puppeteer downloads. It is
|
||||||
|
fine to re-use the same sandbox executable for different Chromium versions, so the following could be
|
||||||
|
done only once per host environment:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# cd to the downloaded instance
|
||||||
|
cd <project-dir-path>/node_modules/puppeteer/.local-chromium/linux-<revision>/chrome-linux/
|
||||||
|
sudo chown root:root chrome_sandbox
|
||||||
|
sudo chmod 4755 chrome_sandbox
|
||||||
|
# copy sandbox executable to a shared location
|
||||||
|
sudo cp chrome_sandbox /usr/local/sbin/chrome-devel-sandbox
|
||||||
|
# export CHROME_DEVEL_SANDBOX env variable
|
||||||
|
export CHROME_DEVEL_SANDBOX=/usr/local/sbin/chrome-devel-sandbox
|
||||||
|
```
|
||||||
|
|
||||||
|
You might want to export the `CHROME_DEVEL_SANDBOX` env variable by default. In this case, add the following to the `~/.bashrc`
|
||||||
|
or `.zshenv`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
export CHROME_DEVEL_SANDBOX=/usr/local/sbin/chrome-devel-sandbox
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
## Running Puppeteer on Travis CI
|
## Running Puppeteer on Travis CI
|
||||||
|
|
||||||
To run headless Chrome on Travis, you *must* call `launch()` with flags to disable Chrome's sandbox, like so:
|
> 👋 We run our tests for Puppeteer on Travis CI - see our [`.travis.yml`](https://github.com/GoogleChrome/puppeteer/blob/master/.travis.yml) for reference.
|
||||||
|
|
||||||
```js
|
Tips-n-tricks:
|
||||||
const browser = await puppeteer.launch({args: ['--no-sandbox']});
|
- The `libnss3` package must be installed in order to run Chromium on Ubuntu Trusty
|
||||||
```
|
- [user namespace cloning](http://man7.org/linux/man-pages/man7/user_namespaces.7.html) should be enabled to support
|
||||||
|
proper sandboxing
|
||||||
|
- [xvfb](https://en.wikipedia.org/wiki/Xvfb) should be launched in order to run Chromium in non-headless mode (e.g. to test Chrome Extensions)
|
||||||
|
|
||||||
Some Puppeteer functionality (like Chrome extensions) requires non-headless mode. Running Puppeteer in non-headless mode on Travis CI can be done using an [Xvfb](https://en.wikipedia.org/wiki/Xvfb) server:
|
To sum up, your `.travis.yml` might look like this:
|
||||||
|
|
||||||
```yml
|
```yml
|
||||||
|
language: node_js
|
||||||
|
dist: trusty
|
||||||
|
addons:
|
||||||
|
apt:
|
||||||
|
packages:
|
||||||
|
# This is required to run new chrome on old trusty
|
||||||
|
- libnss3
|
||||||
|
notifications:
|
||||||
|
email: false
|
||||||
|
cache:
|
||||||
|
directories:
|
||||||
|
- node_modules
|
||||||
|
# allow headful tests
|
||||||
before_install:
|
before_install:
|
||||||
- export DISPLAY=:99.0
|
# Enable user namespace cloning
|
||||||
- sh -e /etc/init.d/xvfb start
|
- "sysctl kernel.unprivileged_userns_clone=1"
|
||||||
|
# Launch XVFB
|
||||||
|
- "export DISPLAY=:99.0"
|
||||||
|
- "sh -e /etc/init.d/xvfb start"
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
## Running Puppeteer in Docker
|
## Running Puppeteer in Docker
|
||||||
|
|
||||||
|
> 👋 We use [Cirrus Ci](https://cirrus-ci.org/) to run our tests for Puppeteer in a Docker container - see our [`Dockerfile.linux`](https://github.com/GoogleChrome/puppeteer/blob/master/.ci/node8/Dockerfile.linux) for reference.
|
||||||
|
|
||||||
Getting headless Chrome up and running in Docker can be tricky.
|
Getting headless Chrome up and running in Docker can be tricky.
|
||||||
The bundled Chromium that Puppeteer installs is missing the necessary
|
The bundled Chromium that Puppeteer installs is missing the necessary
|
||||||
shared library dependencies.
|
shared library dependencies.
|
||||||
|
Loading…
Reference in New Issue
Block a user