Merge pull request #99 from ovh/docfix

doc: minor adjustments

README.md

@@ -125,7 +125,7 @@ Even with the most conservative, precautionous and paranoid coding process, code
 - The bastion main script is declared as the bastion user's system shell:
     - No user has real (`bash`-like) shell access on the system
     - All code is ran under the unprivileged user's system account rights
-    - Even if a user could escape to a real shell, he wouldn't be able to connect to machines he doesn't have access to, because he doesn't have filesystem-level read access to the SSH keys
+    - Even if a user could escape to a real shell, they wouldn't be able to connect to machines they don't have access to, because they don't have filesystem-level read access to the SSH keys
 
 - The code is modular
     - The main code mainly checks rights, logs actions, and enable `ssh` access to other machines

doc/sphinx/faq.rst

@@ -41,6 +41,8 @@ They're actually quite low. Down to its basics, the bastion is merely a fancy wr
 
 Now to give you some data points, we've observed that 250 concurrent users take up 2.5 Gb of RAM (including the operating system's own footprint, and the usual daemons such as auditd, syslog, etc.). So a rule of thumb would be 1 Gb per 100 simultaneous sessions. If you expect to get a lot of new connections per minute (not necessarily long-lived), it's advised to use SSD drives however, as the bastion workload pattern for disk I/O is a lot of random seeks to write logs and ttyrecs. Mechanical hard drives are very bad at this.
 
+.. _faq_docker:
+
 Can I run it under Docker in production?
 ========================================
 

doc/sphinx/installation/basic.rst

@@ -29,16 +29,18 @@ The following Linux distros are tested with each release, but as this is a secur
 - Debian 10 (Buster), 9 (Stretch), 8 (Jessie)
 - RHEL/CentOS 8.x (8.3.2011, 8.2.2004, 8.1.1911), 7.x (7.9.2009, 7.8.2003, 7.7.1908)
 - Ubuntu LTS 20.04, 18.04, 16.04, 14.04\*
-- OpenSUSE Leap 15.2\*, 15.1\*, 15.0\*
+- OpenSUSE Leap 15.2\*, 15.1\*, 15.0\*\*
 
 \*: Note that these versions have no out-of-the-box MFA support, as they lack packaged versions of ``pamtester``, ``pam-google-authenticator``, or both. Of course, you may compile those yourself.
 Any other so-called `modern` Linux version are not tested with each release, but should work with no or minor adjustments.
 
+\*\*: OpenSUSE Leap 15.0 randomly hits a segfault when `updating system packages <https://bugzilla.opensuse.org/show_bug.cgi?id=1146027>`_, we had to remove it from our automated tests workflow.
+
 The following OS are also tested with each release:
 
-- FreeBSD/HardenedBSD 12.1\*\*
+- FreeBSD/HardenedBSD 12.1\*\*\*
 
-\*\*: Note that these have partial MFA support, due to their reduced set of available ``pam`` plugins. Support for either an additional password or TOTP factor can be configured, but not both at the same time. The code is actually known to work on FreeBSD/HardenedBSD 10+, but it's only regularly tested under 12.1.
+\*\*\*: Note that these have partial MFA support, due to their reduced set of available ``pam`` plugins. Support for either an additional password or TOTP factor can be configured, but not both at the same time. The code is actually known to work on FreeBSD/HardenedBSD 10+, but it's only regularly tested under 12.1.
 
 Other BSD variants partially work but are unsupported and discouraged as they have a severe limitation over the maximum number of supplementary groups (causing problems for group membership and restricted commands checks), no filesystem-level ACL support and missing MFA:
 

doc/sphinx/installation/docker.rst

@@ -2,7 +2,17 @@
 Sandbox using Docker
 ====================
 
-- Let's build the docker image and run it
+This is a good way to test The Bastion within seconds, but :ref:`read the FAQ <faq_docker>` if you're serious about using containerization in production.
+
+The sandbox image is available for the following architectures: ``linux/386``, ``linux/amd64``, ``linux/arm/v6``, ``linux/arm/v7``, ``linux/arm64``, ``linux/ppc64le``, ``linux/s390x``.
+
+- Let's run the docker image:
+
+.. code-block:: shell
+
+    docker run -d -p 22 --name bastiontest ovhcom/the-bastion:sandbox
+
+- Or, if you prefer building the docker image yourself, you can: use the two commands below. Of course, if you already typed the ``docker run`` command above, you can skip the following commands:
 
 .. code-block:: shell
 
@@ -15,7 +25,7 @@ Sandbox using Docker
 
     docker exec -it bastiontest /opt/bastion/bin/admin/setup-first-admin-account.sh poweruser auto
 
-- We're now up and running with the default configuration! Let's setup a handy bastion alias, and test the `info` command:
+- We're now up and running with the default configuration! Let's setup a handy bastion alias, and test the ``info`` command:
 
 .. code-block:: shell
 
@@ -29,7 +39,7 @@ Sandbox using Docker
 
     bastion -i
 
-- This is useful to call several `--osh` plugins in a row. Now we can ask for help to see all plugins:
+- This is useful to call several ``--osh`` plugins in a row. Now we can ask for help to see all plugins:
 
 .. code-block:: shell
 
@@ -41,7 +51,7 @@ Sandbox using Docker
 
     $> selfListEgressKeys
 
-- Copy this public key to the remote machine's `authorized_keys` under the `.ssh/` folder of the account you want to connect to, then:
+- Copy this public key to the remote machine's ``authorized_keys`` under the ``.ssh/`` folder of the account you want to connect to, then:
 
 .. code-block:: shell