ovh/the-bastion
1
1
Fork 0
mirror of https://github.com/ovh/the-bastion.git synced 2025-02-25 08:04:38 +08:00
Code Issues Projects Releases Packages Wiki Activity

Merge pull request #31 from ovh/doc

Browse source 
A few documentation fixes
This commit is contained in:
Stéphane Lesimple 2020-11-03 18:46:51 +01:00 committed by GitHub
commit 4519fbda75
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 23 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
doc/sphinx/Makefile
View file

@ -7,9 +7,13 @@ SPHINXBUILD = sphinx-build
SOURCEDIR = .
BUILDDIR = _build
VERSION_FILES = conf.py installation/basic.rst
VERSION := $(shell perl -e 'require "../../lib/perl/OVH/Bastion.pm"; print $$OVH::Bastion::VERSION')
all: plugins default
default: Makefile
@sed -i -e "s/__VERSION__/$(VERSION)/g" $(VERSION_FILES)
@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
@rsync -a --delete _build/html/ ../../docs/
@echo "HTML documentation copied to ../../docs/"

4
doc/sphinx/conf.py
View file

@ -24,9 +24,9 @@ copyright = '2020, OVHcloud'
author = 'The Bastion Authors'
# The short X.Y version
version = '3.00.00'
version = '__VERSION__'
# The full version, including alpha/beta/rc tags
release = '3.00.00'
release = '__VERSION__'
# -- General configuration ---------------------------------------------------

13
doc/sphinx/faq.rst
View file

@ -39,7 +39,7 @@ What are the recommended hardware specifications?
They're actually quite low. Down to its basics, the bastion is merely a fancy wrapper around ``ssh``, so if you have a device that handles ``ssh`` well, it'll handle the bastion just fine.
Now to give you some data points, we've observed that 1000 concurrent users take up FIXME Gb of RAM (including the operating system's own footprint, and the usual daemons such as auditd, syslog, etc.). If you expect to get to at least hundreds of simultaneous sessions, it's advised to use SSD drives however, as the bastion workload pattern for disk I/O is a lot of random seeks, and mechanical hard drives are very bad at this.
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.
Can I run it under Docker in production?
========================================
@ -48,6 +48,17 @@ Technically you can, but you have to think about what are the implications (this
Note that the provided Dockerfiles are a good start, but no volumes are defined. To ensure that all the accounts don't disappear on a ``docker rm``, you would at least need to ensure that ``/home``, ``/etc/passwd``, ``/etc/shadow``, ``/etc/group``, ``/etc/gshadow`` are stored in a volume, in addition to ``/etc/bastion`` and ``/root/.gpg``. You'll also need an SSH server, obviously, and probably a ``syslog-ng`` daemon.
.. _faq_existing_server:
Can I install it on my already existing server?
===============================================
This is discouraged if your server is already doing something else, such as hosting a website, handling your e-mails or running a database.
From a security standpoint, it's a bad idea because if your server gets hacked due to one of the other services you're hosting, the SSH keys could get compromised even if The Bastion itself has no security issue.
This is also discouraged due to the design of The Bastion: being deeply intertwined with the OS it's running on, it might make changes that seem intrusive from the point of view of other running services. Such as creating and deleting system accounts and groups from time to time, modifying the PAM configuration, or hardening the SSH client and server configurations system-wide, which could break other services or workflows that expect to be running on a default (non-hardened) SSH configuration.
.. _faq_jumphost:
How to use The Bastion with the SSH ``ProxyCommand`` option?

6
doc/sphinx/installation/basic.rst
View file

@ -7,6 +7,10 @@ If you are just upgrading from a previous version, please read :doc:`upgrading<u
1. Operating system
===================
.. warning::
The Bastion expects to be the only main service runnning on the server, please see :ref:`this FAQ entry <faq_existing_server>` for more information.
The following Linux distros are tested with each release, but as this is a security product, you are *warmly* advised to run it on the latest up-to-date stable version of your favorite OS:
- Debian 10 (Buster), 9 (Stretch), 8 (Jessie)
@ -52,7 +56,7 @@ Get the tarball of the latest release, which can be found `here <https://github.
.. code-block:: shell
test -d /opt/bastion || mkdir -p /opt/bastion
tar -C /opt/bastion v3.00.00.tar.gz
tar -C /opt/bastion v__VERSION__.tar.gz
The code supports being hosted somewhere else on the filesystem hierarchy, but this is discouraged as you might need to adjust a lot of configuration files (notably sudoers.d, cron.d, init.d) that needs an absolute path.
You should end up with directories such as ``bin``, ``lib``, etc. directly under ``/opt/bastion``.