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

doc: autogenerate the bastion.conf options reference

Browse source
This commit is contained in:
Stéphane Lesimple 2020-12-16 12:41:09 +00:00
parent ef6efa6dc3
commit ea6867a614
No known key found for this signature in database
GPG key ID: 4B4A3289E9D35658
7 changed files with 1435 additions and 293 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
doc/sphinx/Makefile
View file

@ -12,7 +12,7 @@ VERSION := $(shell perl -e 'require "../../lib/perl/OVH/Bastion.pm"; print
all: autogenerated default
autogenerated: plugins
autogenerated: plugins bastion_conf
default: Makefile
@sed -i -e "s/__VERSION__/$(VERSION)/g" $(VERSION_FILES)
@ -27,7 +27,10 @@ help:
plugins:
@bash build-plugins-help.sh
.PHONY: help Makefile plugins all autogenerated default
bastion_conf:
@perl build-bastion-conf-help.pl < ../../etc/bastion/bastion.conf.dist > administration/bastion_conf.rst
.PHONY: help Makefile plugins all autogenerated default bastion_conf
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).

946
doc/sphinx/administration/bastion_conf.rst Normal file
View file

@ -0,0 +1,946 @@
======================
bastion.conf reference
======================
.. note::
The Bastion has a lot of configuration options so that you can tailor it to your needs.
However, if you're just starting and would like to get started quickly, just configure
the ``Main Options``. All the other options have sane defaults that can still be customized
at a later time.
Option List
===========
Main Options
------------
Those are the options you should customize when first setting up a bastion. All the other options have sane defaults and can be customized later if needed.
- :ref:`bastion_conf_bastionName`
- :ref:`bastion_conf_bastionCommand`
- :ref:`bastion_conf_readOnlySlaveMode`
- :ref:`bastion_conf_adminAccounts`
- :ref:`bastion_conf_superOwnerAccounts`
SSH Policies
------------
All the options related to the SSH configuration and policies, both for ingress and egress connections.
- :ref:`bastion_conf_allowedIngressSshAlgorithms`
- :ref:`bastion_conf_allowedEgressSshAlgorithms`
- :ref:`bastion_conf_minimumIngressRsaKeySize`
- :ref:`bastion_conf_maximumIngressRsaKeySize`
- :ref:`bastion_conf_minimumEgressRsaKeySize`
- :ref:`bastion_conf_maximumEgressRsaKeySize`
- :ref:`bastion_conf_defaultAccountEgressKeyAlgorithm`
- :ref:`bastion_conf_defaultAccountEgressKeySize`
- :ref:`bastion_conf_moshAllowed`
- :ref:`bastion_conf_moshTimeoutNetwork`
- :ref:`bastion_conf_moshTimeoutSignal`
- :ref:`bastion_conf_moshCommandLine`
Global network policies
-----------------------
Those options can set a few global network policies to be applied bastion-wide.
- :ref:`bastion_conf_allowedNetworks`
- :ref:`bastion_conf_forbiddenNetworks`
- :ref:`bastion_conf_ingressToEgressRules`
Logging
-------
Options to customize how logs should be produced.
- :ref:`bastion_conf_enableSyslog`
- :ref:`bastion_conf_syslogFacility`
- :ref:`bastion_conf_syslogDescription`
- :ref:`bastion_conf_enableGlobalAccessLog`
- :ref:`bastion_conf_enableAccountAccessLog`
- :ref:`bastion_conf_enableGlobalSqlLog`
- :ref:`bastion_conf_enableAccountSqlLog`
- :ref:`bastion_conf_ttyrecFilenameFormat`
- :ref:`bastion_conf_ttyrecAdditionalParameters`
Other ingress policies
----------------------
Policies applying to the ingress connections
- :ref:`bastion_conf_ingressKeysFrom`
- :ref:`bastion_conf_ingressKeysFromAllowOverride`
Other egress policies
---------------------
Policies applying to the egress connections
- :ref:`bastion_conf_defaultLogin`
- :ref:`bastion_conf_egressKeysFrom`
- :ref:`bastion_conf_keyboardInteractiveAllowed`
- :ref:`bastion_conf_passwordAllowed`
- :ref:`bastion_conf_telnetAllowed`
Session policies
----------------
Options to customize the established sessions behaviour
- :ref:`bastion_conf_displayLastLogin`
- :ref:`bastion_conf_interactiveModeAllowed`
- :ref:`bastion_conf_interactiveModeTimeout`
- :ref:`bastion_conf_interactiveModeByDefault`
- :ref:`bastion_conf_idleLockTimeout`
- :ref:`bastion_conf_idleKillTimeout`
- :ref:`bastion_conf_warnBeforeLockSeconds`
- :ref:`bastion_conf_warnBeforeKillSeconds`
- :ref:`bastion_conf_accountExternalValidationProgram`
- :ref:`bastion_conf_accountExternalValidationDenyOnFailure`
- :ref:`bastion_conf_alwaysActiveAccounts`
Account policies
----------------
Policies applying to the bastion accounts themselves
- :ref:`bastion_conf_accountMaxInactiveDays`
- :ref:`bastion_conf_accountExpiredMessage`
- :ref:`bastion_conf_accountCreateSupplementaryGroups`
- :ref:`bastion_conf_accountCreateDefaultPersonalAccesses`
- :ref:`bastion_conf_accountMFAPolicy`
- :ref:`bastion_conf_MFAPasswordMinDays`
- :ref:`bastion_conf_MFAPasswordMaxDays`
- :ref:`bastion_conf_MFAPasswordWarnDays`
- :ref:`bastion_conf_MFAPasswordInactiveDays`
- :ref:`bastion_conf_MFAPostCommand`
Other options
-------------
These options are either discouraged (in which case this is explained in the description) or rarely need to be modified.
- :ref:`bastion_conf_accountUidMin`
- :ref:`bastion_conf_accountUidMax`
- :ref:`bastion_conf_ttyrecGroupIdOffset`
- :ref:`bastion_conf_documentationURL`
- :ref:`bastion_conf_debug`
- :ref:`bastion_conf_remoteCommandEscapeByDefault`
- :ref:`bastion_conf_sshClientDebugLevel`
- :ref:`bastion_conf_sshClientHasOptionE`
Option Reference
================
Main Options
------------
.. _bastion_conf_bastionName:
bastionName
***********
:Type: ``string``
:Default: ``"fix-my-config-please-missing-bastion-name"``
This will be the name advertised in the aliases admins will give to bastion users, and also in the banner of the plugins output. You can see it as a friendly name everybody will use to refer to this machine: something more friendly than just its full hostname.
.. _bastion_conf_bastionCommand:
bastionCommand
**************
:Type: ``string``
:Default: ``"ssh USER@HOSTNAME -t --"``
The ``ssh`` command to launch to connect to this bastion as a user. This will be printed on ``accountCreate``, so that the new user knows how to connect. Magic tokens are:
- ACCOUNT or USER: replaced at runtime by the account name
- BASTIONNAME: replaced at runtime by the name defined in ``bastionName``
- HOSTNAME: replaced at runtime by the hostname of the system
So, for example if your specify ``ssh USER@HOSTNAME -t --``, it'll give ``johndoe@bastion1.example.org -t --`` as a bastion alias to *johndoe*
.. _bastion_conf_readOnlySlaveMode:
readOnlySlaveMode
*****************
:Type: ``boolean``
:Default: ``false``
If set to ``false``, this bastion will work in standalone mode, or will be the master in a master/slave mode. If set to ``true``, this'll be the slave which means all plugins that modify groups, accounts, or access rights will be disabled, and the master bastion will push its modifications using inotify/rsync, please refer do the documentation to set this up.
.. _bastion_conf_adminAccounts:
adminAccounts
*************
:Type: ``array of strings (account names)``
:Default: ``[]``
The list of accounts that are Admins of the bastion. Admins can't be deleted or otherwise modified by non-admins. They also gain access to special dangerous/sensitive ``--osh`` commands, such as being able to impersonate anybody else. Note that an Admin is also always considered as a Super Owner, which means they also override all checks of group administrative commands. Don't forget to add them to the ``osh-admin`` group too (system-wise), or they won't really be considered as Admins: this is an additional security measure against privilege escalation. Rule of thumb: it's probably a good idea to only add here people that have ``root`` access to the bastion machine itself.
.. _bastion_conf_superOwnerAccounts:
superOwnerAccounts
******************
:Type: ``array of strings (account names)``
:Default: ``[]``
The list of accounts that are "Super Owners". They can run all group administrative commands, exactly as if they were implicitly owners of all the groups. Super Owners are only here as a last resort when the owners/gatekeepers/aclkeepers of a group are not available. Every command run by a Super Owner that would have failed if the account was not a Super Owner is logged explicitly as "Super Owner Override", you might want to add a rule for those in your SIEM. You can consider than the Super Owners have an implicit *sudo* for group management. Don't add here accounts that are bastion Admins, as they already inherit the Super Owner role.
SSH Policies
------------
.. _bastion_conf_allowedIngressSshAlgorithms:
allowedIngressSshAlgorithms
***************************
:Type: ``array of strings (algorithm names)``
:Default: ``[ "rsa", "ecdsa", "ed25519" ]``
The algorithms authorized for ingress ssh public keys added to this bastion. Possible values: ``dsa``, ``rsa``, ``ecdsa``, ``ed25519``, note that some of those might not be supported by your current version of ``OpenSSH``: unsupported algorithms are automatically omitted at runtime.
.. _bastion_conf_allowedEgressSshAlgorithms:
allowedEgressSshAlgorithms
**************************
:Type: ``array of strings (algorithm names)``
:Default: ``[ "rsa", "ecdsa", "ed25519" ]``
The algorithms authorized for egress ssh public keys generated on this bastion. Possible values: ``dsa``, ``rsa``, ``ecdsa``, ``ed25519``, note that some of those might not be supported by your current version of ``OpenSSH``, unsupported algorithms are automatically omitted at runtime.
.. _bastion_conf_minimumIngressRsaKeySize:
minimumIngressRsaKeySize
************************
:Type: ``int``
:Default: ``2048``
The minimum allowed size for ingress RSA keys (user->bastion). Sane values range from 2048 to 4096.
.. _bastion_conf_maximumIngressRsaKeySize:
maximumIngressRsaKeySize
************************
:Type: ``int``
:Default: ``8192``
The maximum allowed size for ingress RSA keys (user->bastion). Too big values (>8192) are extremely CPU intensive and don't really add that much security.
.. _bastion_conf_minimumEgressRsaKeySize:
minimumEgressRsaKeySize
***********************
:Type: ``int``
:Default: ``2048``
The minimum allowed size for egress RSA keys (bastion->server). Sane values range from 2048 to 4096.
.. _bastion_conf_maximumEgressRsaKeySize:
maximumEgressRsaKeySize
***********************
:Type: ``int``
:Default: ``8192``
The maximum allowed size for ingress RSA keys (bastion->server). Too big values (>8192) are extremely CPU intensive and don't really add that much security.
.. _bastion_conf_defaultAccountEgressKeyAlgorithm:
defaultAccountEgressKeyAlgorithm
********************************
:Type: ``string``
:Default: ``"rsa"``
The default algorithm to use to create the egress key of a newly created account
.. _bastion_conf_defaultAccountEgressKeySize:
defaultAccountEgressKeySize
***************************
:Type: ``int``
:Default: ``4096``
The default size to use to create the egress key of a newly created account (also see ``defaultAccountEgressKeyAlgorithm``)
.. _bastion_conf_moshAllowed:
moshAllowed
***********
:Type: ``boolean``
:Default: ``false``
If set to ``true``, mosh usage is allowed (mosh needs to be installed on serverside, obviously). Otherwise, this feature is disabled.
.. _bastion_conf_moshTimeoutNetwork:
moshTimeoutNetwork
******************
:Type: ``int > 0``
:Default: ``86400``
Number of seconds of inactivity (network-wise) after a mosh-server will exit. By design even if the client is disconnected "for good", mosh-server would wait forever. If mosh is meant to handle shaky connections but not mobility, you can set this to a low value. It sets the ``MOSH_SERVER_NETWORK_TMOUT`` envvar for mosh, see ``man mosh-server`` for more information (mosh 1.2.6+).
.. _bastion_conf_moshTimeoutSignal:
moshTimeoutSignal
*****************
:Type: ``int > 0``
:Default: ``30``
Number of seconds of inactivity (network-wise) a mosh-server will wait after receiving a ``SIGUSR1`` before exiting. It sets the ``MOSH_SERVER_SIGNAL_TMOUT`` envvar for mosh, see ``man mosh-server`` for more information (mosh 1.2.6+).
.. _bastion_conf_moshCommandLine:
moshCommandLine
***************
:Type: ``string``
:Default: ``""``
:Example: ``"-s -p 40000:49999"``
Additional parameters that will be passed as-is to mosh-server. See ``man mosh-server``, you should at least add the ``-p`` option to specify a fixed number of ports (easier for firewall configuration).
Global network policies
-----------------------
.. _bastion_conf_allowedNetworks:
allowedNetworks
***************
:Type: ``array of strings (IPs and/or prefixes)``
:Default: ``[]``
:Example: ``["10.42.0.0/16","192.168.111.0/24","203.0.113.42"]``
Restricts egress connection attempts to those listed networks only. This is enforced at all times and can NOT be overridden by users. If you are lucky enough to have you own IP blocks, it's probably a good idea to list them here. An empty array means no restriction is applied.
.. _bastion_conf_forbiddenNetworks:
forbiddenNetworks
*****************
:Type: ``array of strings (IPs and/or prefixes)``
:Default: ``[]``
:Example: ``["10.42.42.0/24"]``
Prevents egress connection to the listed networks, this takes precedence over ``allowedNetworks``. This can be used to prevent connection to some hosts or subnets in a broadly allowed prefix. This is enforced at all times and can NOT be overridden by users.
.. _bastion_conf_ingressToEgressRules:
ingressToEgressRules
********************
:Type: ``array of rules, a rule being a 3-uple of [array, array, string]``
:Default: ``[]``
Fine-grained rules (a la *netfilter*) to apply global restrictions to possible egress destinations given ingress IPs. This is similar to ``allowedNetworks`` and ``forbiddenNetworks``, but way more powerful (in fact, those two previous options can be expressed exclusively using ``ingressToEgressRules``). Those rules here are enforced at all times and can **NOT** be overridden by users or admins.
Each rule will be processed **IN ORDER**. The first rule to match will be applied and no other rule will be checked.
If no rule matches, the default is to apply no restriction.
A rule is a 3-uple of [``array of ingress networks``, ``array of egress networks``, ``policy to apply``].
- ``array of ingress networks``: if the IP of the ingress connection matches a network or IP in this list, the rule *may* apply: we proceed to check the egress network IP
- ``array of egress networks``: if the IP of the egress connection matches a network or IP in this list, the rule *does* apply and we'll enforce the policy defined in the third item of the rule
- ``policy to apply``: this is what to enforce when the ingress and egress network match
The "policy to apply" item can have 3 values:
- ``ALLOW``, no restriction will be applied (all rights-check of groups and personal accesses still apply)
- ``DENY``, access will be denied regardless of any group or personal accesses
- ``ALLOW-EXCLUSIVE``, access will be allowed **if and only if** the egress network match, given the ingress network. In other words, if the ingress IP matches one of the ingress networks specified in the rule, but the egress IP **DOES NOT** match any of the egress network specified, access will be denied. This is an easy way to ensure that a given list of ingress networks can only access a precise list of egress networks and nothing else.
For example, take the following configuration:
::
[
[["10.19.0.0/16","10.15.15.0/24"], ["10.20.0.0/16"], "ALLOW-EXCLUSIVE"],
[["192.168.42.0/24"], ["192.168.42.0/24"], "ALLOW"],
[["192.168.0.0/16"], ["192.168.0.0/16"], "DENY"]
]
- The ``10.19.0.0/16`` and ``10.15.15.0/24`` networks can only access the ``10.20.0.0/16`` network (rule ``#1``)
- The ``192.168.42.0/24`` network can access any machine from its own /24 network (rule ``#2``), but not any other machine from the wider ``192.168.0.0/16`` network (rule ``#3``). It can however access any other machine outside of this block (implicit allow catch-all rule, as there is no corresponding ``DENY`` rule, and rule ``#2`` is ``ALLOW`` and not ``ALLOW-EXCLUSIVE``)
- The ``192.168.0.0/16`` network (except ``192.168.42.0/16``) can access any machine except one from its own network (rule ``#3``)
- All the other networks can access any other network (including egress ``10.20.0.0/16`` or egress ``192.168.0.0/16``)
In any case, all the personal and group accesses still apply in addition to these global rules.
Logging
-------
.. _bastion_conf_enableSyslog:
enableSyslog
************
:Type: ``boolean``
:Default: ``true``
If set to ``false``, syslog will be disabled. If set to ``true``, we'll send logs through syslog (don't forget to setup your syslog daemon!).
.. _bastion_conf_syslogFacility:
syslogFacility
**************
:Type: ``string``
:Default: ``"local7"``
Sets the facility that will be used for syslog.
.. _bastion_conf_syslogDescription:
syslogDescription
*****************
:Type: ``string``
:Default: ``"bastion"``
Sets the description that will be used for syslog.
.. _bastion_conf_enableGlobalAccessLog:
enableGlobalAccessLog
*********************
:Type: ``boolean``
:Default: ``true``
If set to ``true``, all accesses will still be logged in ``/home/osh.log``. This file is never rotated and is world writable, this is discouraged: please use syslog insteead.
.. _bastion_conf_enableAccountAccessLog:
enableAccountAccessLog
**********************
:Type: ``boolean``
:Default: ``true``
If set to ``true``, all accesses will still be logged in the user's home ``/home/USER/USER-log-YYYYMM.log``. If set to ``false``, we won't log there.
.. _bastion_conf_enableGlobalSqlLog:
enableGlobalSqlLog
******************
:Type: ``boolean``
:Default: ``true``
If set to ``true``, all accesses will be logged (in a short SQL format) in ``/home/logkeeper/*.sqlite``. If set to ``false``, we won't log there.
.. _bastion_conf_enableAccountSqlLog:
enableAccountSqlLog
*******************
:Type: ``boolean``
:Default: ``true``
If set to ``true``, all accesses will be logged (in a detailed SQL format) in the user's home ``/home/USER/USER-log-YYYYMM.sqlite``. Otherwise, we won't log there.
.. _bastion_conf_ttyrecFilenameFormat:
ttyrecFilenameFormat
********************
:Type: ``string``
:Default: ``"%Y-%m-%d.%H-%M-%S.#usec#.&uniqid.ttyrec"``
Sets the filename format of the output files of ttyrec for a given session. Magic tokens are: ``&bastionname``, ``&uniqid``, ``&account``, ``&ip``, ``&port``, ``&user`` (they'll be replaced by the corresponding values of the current session). Then, this string (automatically prepended with the correct folder) will be passed to ttyrec's ``-F`` parameter, which uses ``strftime()`` to expand it, so the usual character conversions will be done (``%Y`` for the year, ``%H`` for the hour, etc., see ``man strftime``). Note that in a addition to the usual ``strftime()`` conversion specifications, ttyrec also supports ``#usec#``, to be replaced by the current microsecond value of the time.
.. _bastion_conf_ttyrecAdditionalParameters:
ttyrecAdditionalParameters
**************************
:Type: ``array of strings``
:Default: ``[]``
:Example: ``["-s", "This is a message with spaces", "--zstd"]``
Additional parameters you want to pass to ``ttyrec`` invocation. Useful, for example, to enable on-the-fly compression, disable cheatcodes, or set/unset any other ``ttyrec`` option. This is an ARRAY, not a string.
Other ingress policies
----------------------
.. _bastion_conf_ingressKeysFrom:
ingressKeysFrom
***************
:Type: ``array of strings (list of IPs and/or prefixes)``
:Default: ``[]``
This array of IPs (or prefixes, such as ``10.20.30.0/24``) will be used to build the ``from="..."`` in front of the ingress account public keys used to connect to the bastion (in ``accountCreate`` or ``selfAddIngressKey``). If the array is empty, then **NO** ``from="..."`` is added (this lowers the security).
.. _bastion_conf_ingressKeysFromAllowOverride:
ingressKeysFromAllowOverride
****************************
:Type: ``boolean``
:Default: ``true``
If set to ``false``, any user-specified ``from="..."`` prefix on keys in commands such as ``selfAddIngressKey`` or ``accountCreate`` are silently ignored and replaced by the IPs in the ``ingressKeysFrom`` configuration option (if any).
If set to ``true``, any user-specified ``from="..."`` will override the value set in ``ingressKeysFrom`` (if any).
Note that when no user-specified ``from="..."`` appears, the value of ``ingressKeysFrom`` is still used, regardless of this option.
Other egress policies
---------------------
.. _bastion_conf_defaultLogin:
defaultLogin
************
:Type: ``string``
:Default: ``""``
The default remote user to use for egress ssh connections where no user has been specified by our caller. If set to the empty string (``""``), will default to the account name of the caller. If your bastion is mainly used to connect as ``root`` on remote systems, you might want to set this to ``root`` for example, to spare a few keystrokes to your users. This is only used when no user is specified on the connection line. For example if your bastion alias is ``bssh``, and you say ``bssh srv1.example.net``, the value of the ``defaultLogin`` value will be used as the user to login as remotely.
.. _bastion_conf_egressKeysFrom:
egressKeysFrom
**************
:Type: ``array of strings (IPs and/or prefixes)``
:Default: ``[]``
These IPs will be added to the ``from="..."`` of the personal account keys and the group keys. Typically you want to specify only the bastions IP here (including all the slaves). Note that if this option is NOT set at all or set to the empty array, it will default to autodetection at runtime (using ``hostname --all-ip-addresses`` under the hood). This is dependent from your system configuration and is therefore discouraged.
.. _bastion_conf_keyboardInteractiveAllowed:
keyboardInteractiveAllowed
**************************
:Type: ``boolean``
:Default: ``true``
If set to ``true``, will allow keyboard-interactive authentication when publickey auth is requested for egress connections, this is needed e.g. for 2FA.
.. _bastion_conf_passwordAllowed:
passwordAllowed
***************
:Type: ``boolean``
:Default: ``false``
If set to ``true``, will allow password authentication for egress ssh, so that user can type his remote password interactively.
.. _bastion_conf_telnetAllowed:
telnetAllowed
*************
:Type: ``boolean``
:Default: ``false``
If set to ``true``, will allow telnet egress connections (``-e`` / ``--telnet``).
Session policies
----------------
.. _bastion_conf_displayLastLogin:
displayLastLogin
****************
:Type: ``boolean``
:Default: ``true``
If ``true``, display their last login information on connection to your users.
.. _bastion_conf_interactiveModeAllowed:
interactiveModeAllowed
**********************
:Type: ``boolean``
:Default: ``true``
If set to ``true``, ``--interactive`` mode is allowed. Otherwise, this feature is disabled.
.. _bastion_conf_interactiveModeTimeout:
interactiveModeTimeout
**********************
:Type: ``int (seconds)``
:Default: ``60``
The number of idle seconds after which the user is disconnected from the bastion when in interactive mode. A value of 0 will disable this feature (user will never be disconnected for idle timeout).
.. _bastion_conf_interactiveModeByDefault:
interactiveModeByDefault
************************
:Type: ``boolean``
:Default: ``true``
If ``true``, drops the user to interactive mode if nothing is specified on the command line. If ``false``, displays the help and exits with an error. Note that for ``true`` to have the expected effect, interactive mode must be enabled (see the ``interactiveModeAllowed`` option above).
.. _bastion_conf_idleLockTimeout:
idleLockTimeout
***************
:Type: ``int >= 0``
:Default: ``0``
If set to a positive value >0, the number of seconds of input idle time after which the session is locked. If ``false``, disabled.
.. _bastion_conf_idleKillTimeout:
idleKillTimeout
***************
:Type: ``int >= 0``
:Default: ``0``
If set to a positive value >0, the number of seconds of input idle time after which the session is killed. If ``false``, disabled. If ``idleLockTimeout`` is set, this value must be higher (obviously).
.. _bastion_conf_warnBeforeLockSeconds:
warnBeforeLockSeconds
*********************
:Type: ``int >= 0``
:Default: ``0``
If set to a positive value >0, the number of seconds before ``idleLockTimeout`` where the user will receive a warning message telling him about the upcoming lock of his session.
.. _bastion_conf_warnBeforeKillSeconds:
warnBeforeKillSeconds
*********************
:Type: ``int >= 0``
:Default: ``0``
If set to a positive value >0, the number of seconds before ``idleKillTimeout`` where the user will receive a warning message telling him about the upcoming kill of his session.
.. _bastion_conf_accountExternalValidationProgram:
accountExternalValidationProgram
********************************
:Type: ``string (path to a binary)``
:Default: ``""``
:Example: ``"$BASEDIR/bin/other/check-active-account-simple.pl"``
Binary or script that will be called by the bastion, with the account name in parameter, to check whether this account should be allowed to connect to the bastion. If empty, this check is skipped. ``$BASEDIR`` is a magic token that is replaced by where the bastion code lives (usually, ``/opt/bastion``).
You can use this configuration parameter to counter-verify all accounts against an external system, for example an *LDAP*, an *Active Directory*, or any system having a list of identities, right when they're connecting to the bastion (on the ingress side). However, it is advised to avoid calling an external system in the flow of an incoming connection, as this violates the "the bastion must be working at all times, regardless of the status of the other components of the company's infrastructure" rule. Instead, you should have a cronjob to periodically fetch all the allowed accounts from said external system, and store this list somewhere on the bastion, then write a simple script that will be called by the bastion to verify whether the connecting account is present on this locally cached list.
An account present in this list is called an *active account*, in the bastion's jargon. An *inactive* account is an account existing on the bastion, but not in this list, and won't be able to connect. Note that for security reasons, inactive bastions administrators would be denied as any other account.
The result is interpreted from the program's exit code. If the program return 0, the account is deemed active. If the program returns 1, the account is deemed inactive. A return code of 2, 3 or 4 indicates a failure of the program in determining the activeness of the account. In this case, the decision to allow or deny the access is determined by the ``accountExternalValidationDenyOnFailure`` option below. Status code 3 additionally logs the ``stderr`` of the program *silently* to the syslog: this can be used to warn admins of a problem without leaking information to the user. Status code 4 does the same, but the ``stderr`` is also shown directly to the user. Any other return code deems the account inactive (same behavior that return code 1).
.. _bastion_conf_accountExternalValidationDenyOnFailure:
accountExternalValidationDenyOnFailure
**************************************
:Type: ``boolean``
:Default: ``true``
If we can't validate an account using the program configured in ``accountExternalValidationProgram``, for example because the path doesn't exist, the file is not executable, or because the program returns the exit code 4 (see above for more information), this configuration option indicates whether we should deny or allow access.
Note that the bastion admins will always be allowed if the ``accountExternalValidationProgram`` doesn't work correctly, because they're expected to be able to fix it. They would be denied, as any other account, if ``accountExternalValidationProgram`` works correctly and denies them access, however. If you're still testing your account validation procedure, and don't want to break your users workflow while you're not 100% sure it works correctly, you can say ``false`` here, and return 4 instead of 1 in your ``accountExternalValidationProgram`` when you would want to deny access.
.. _bastion_conf_alwaysActiveAccounts:
alwaysActiveAccounts
********************
:Type: ``array of strings (account names)``
:Default: ``[]``
List of accounts which should NOT be checked against the ``accountExternalValidationProgram`` mechanism above (for example bot accounts). This can also be set per-account at account creation time or later with the ``accountModify`` plugin's ``--always-active`` flag.
Account policies
----------------
.. _bastion_conf_accountMaxInactiveDays:
accountMaxInactiveDays
**********************
:Type: ``int``
:Default: ``0``
If > 0, deny access to accounts that didn't log in since at least that many days. A value of 0 means that this functionality is disabled (we will never deny access for inactivity reasons).
.. _bastion_conf_accountExpiredMessage:
accountExpiredMessage
*********************
:Type: ``string``
:Default: ``""``
If non-empty, customizes the message that will be printed to a user attempting to connect with an expired account (see ``accountMaxInactiveDays`` above). When empty, defaults to the standard message "Sorry, but your account has expired (#DAYS# days), access denied by policy.". The special token ``#DAYS#`` is replaced by the number of days since we've last seen this user.
.. _bastion_conf_accountCreateSupplementaryGroups:
accountCreateSupplementaryGroups
********************************
:Type: ``array of strings (system group names)``
:Default: ``[]``
List of system groups to add a new account to when its created (see ``accountCreate``). Can be useful to grant some restricted commands by default to new accounts. For example ``osh-selfAddPersonalAccess``, ``osh-selfDelPersonalAccess``, etc. Note that the group here are **NOT** *bastion groups*, but system groups.
.. _bastion_conf_accountCreateDefaultPersonalAccesses:
accountCreateDefaultPersonalAccesses
************************************
:Type: ``array of strings (list of IPs and/or prefixes)``
:Default: ``[]``
List of strings of the form USER@IP or USER@IP:PORT or IP or IP:PORT, with IP being IP or prefix (such as 1.2.3.0/24). This is the list of accesses to add to the personal access list of newly created accounts. The special value ACCOUNT is replaced by the name of the account being created. This can be useful to grant some accesses by default to new accounts (for example ACCOUNT@0.0.0.0/0)
.. _bastion_conf_accountMFAPolicy:
accountMFAPolicy
****************
:Type: ``string``
:Default: ``"enabled"``
Set a MFA policy for the bastion accounts, the supported values are:
- ``disabled``: the commands to setup TOTP and UNIX account password are disabled, nobody can setup MFA for himself or others. Already configured MFA still applies, unless the sshd configuration is modified to no longer call PAM on the authentication phase
- ``password-required``: for all accounts, a UNIX account password is required in addition to the ingress SSH public key. On first connection with his SSH key, the user is forced to setup a password for his account, and can't disable it afterwards
- ``totp-required``: for all accounts, a TOTP is required in addition to the ingress SSH public key. On first connection with his SSH key, the user is forced to setup a TOTP for his account, and can't disable it afterwards
- ``any-required``: for all accounts, either a TOTP or an UNIX account password is required in addition to the ingress SSH public key. On first connection with his SSH key, the user is forced to setup either of those, as he sees fit, and can't disable it afterwards
- ``enabled``: for all accounts, TOTP and UNIX account password are available as opt-in features as the users see fit. Some accounts can be forced to setup either TOTP or password-based MFA if they're flagged accordingly (with the accountModify command)
.. _bastion_conf_MFAPasswordMinDays:
MFAPasswordMinDays
******************
:Type: ``int >= 0``
:Default: ``0``
For the PAM UNIX password MFA, sets the min amount of days between two password changes (see ``chage -m``)
.. _bastion_conf_MFAPasswordMaxDays:
MFAPasswordMaxDays
******************
:Type: ``int >= 0``
:Default: ``90``
For the PAM UNIX password MFA, sets the max amount of days after which the password must be changed (see ``chage -M``)
.. _bastion_conf_MFAPasswordWarnDays:
MFAPasswordWarnDays
*******************
:Type: ``int >= 0``
:Default: ``15``
For the PAM UNIX password MFA, sets the number of days before expiration on which the user will be warned to change his password (see ``chage -W``)
.. _bastion_conf_MFAPasswordInactiveDays:
MFAPasswordInactiveDays
***********************
:Type: ``int >= -1``
:Default: ``-1``
For the PAM UNIX password MFA, the account will be blocked after the password is expired (and not renewed) for this amount of days (see ``chage -E``). -1 disables this feature. Note that this is different from the accountMaxInactiveDays option above, that is handled by the bastion software itself instead of PAM
.. _bastion_conf_MFAPostCommand:
MFAPostCommand
**************
:Type: ``array of strings (a valid system command)``
:Default: ``[]``
:Example: ``["sudo","-n","-u","root","--","/sbin/pam_tally2","-u","%ACCOUNT%","-r"],``
When using JIT MFA (i.e. not directly by calling PAM from SSHD's configuration, but using ``pamtester`` from within the code), execute this command on success.
This can be used for example if you're using ``pam_tally2`` in your PAM MFA configuration, ``pamtester`` can't reset the counter to zero because this is usually done in the ``account_mgmt`` PAM phase. You can use a script to reset it here.
The magic token ``%ACCOUNT%`` will be replaced by the account name.
Other options
-------------
.. _bastion_conf_accountUidMin:
accountUidMin
*************
:Type: ``int``
:Default: ``2000``
Minimum allowed UID for accounts on this bastion. Hardcoded > 100 even if configured for less.
.. _bastion_conf_accountUidMax:
accountUidMax
*************
:Type: ``int``
:Default: ``99999``
Maximum allowed UID for accounts on this bastion.
.. _bastion_conf_ttyrecGroupIdOffset:
ttyrecGroupIdOffset
*******************
:Type: ``int``
:Default: ``100000``
Offset to apply on user group uid to create its ``-tty`` group, should be > ``accountUidMax - accountUidMin`` to ensure there is no overlap.
.. _bastion_conf_documentationURL:
documentationURL
****************
:Type: ``string``
:Default: ``"https://ovh.github.io/the-bastion/"``
The URL of the documentation where users will be pointed to, for example when displaying help. If you have some internal documentation about the bastion, you might want to advertise it here.
.. _bastion_conf_debug:
debug
*****
:Type: ``boolean``
:Default: ``false``
Enables or disables debug *GLOBALLY*, printing a lot of information to anyone using the bastion. Don't enable this unless you're chasing a bug in the code and are familiar with it.
.. _bastion_conf_remoteCommandEscapeByDefault:
remoteCommandEscapeByDefault
****************************
:Type: ``boolean``
:Default: ``false``
If set to ``false``, will not escape simple quotes in remote commands by default. Don't enable this, this is to keep compatibility with an ancient broken behavior. Will be removed in the future. Can be overridden at runtime with ``--never-escape`` and ``--always-escape``.
.. _bastion_conf_sshClientDebugLevel:
sshClientDebugLevel
*******************
:Type: ``int (0-3)``
:Default: ``0``
Indicates the number of ``-v``'s that will be added to the ssh client command line when starting a session. Probably a bad idea unless you want to annoy your users.
.. _bastion_conf_sshClientHasOptionE:
sshClientHasOptionE
*******************
:Type: ``boolean``
:Default: ``false``
Set to ``true`` if your ssh client supports the ``-E`` option and you want to use it to log debug info on opened sessions. **Discouraged** because it has some annoying side effects (some ssh errors then go silent from the user perspective).

14
doc/sphinx/administration/index.rst Normal file
View file

@ -0,0 +1,14 @@
==============
Administration
==============
Here we make the assumption that you've already installed The Bastion, and would like to know more about administration topics.
.. warning::
The options reference of the satellite configuration files (other than bastion.conf)
are not yet documented here, but directly in the configuration files themselves.
.. toctree::
:maxdepth: 3
bastion_conf

117
doc/sphinx/build-bastion-conf-help.pl Normal file
View file

@ -0,0 +1,117 @@
#! /usr/bin/env perl
# vim: set filetype=perl ts=4 sw=4 sts=4 et:
use strict;
use warnings;
my %h;
my @out;
my $section;
my %sections;
my %sectiondesc;
my @orderedsections;
sub dumpdoc {
if (!%h) {
; # nothing to do
}
elsif (defined $h{param} && defined $h{default} && defined $h{desc} && defined $h{type}) {
die "attempting to dump data but section=$section" if !$section;
push @{ $sections{$section} }, $h{param};
push @out, ".. _bastion_conf_$h{param}:\n";
push @out, "\n";
push @out, "$h{param}\n";
my $len = length($h{param});
push @out, "*"x$len."\n\n";
push @out, ":Type: ``$h{type}``\n\n";
push @out, ":Default: ``$h{default}``\n\n";
push @out, ":Example: ``$h{example}``\n\n" if $h{example};
push @out, "$h{desc}\n\n";
}
else {
die "something is missing: ".($h{param}?"":"param ").($h{default}?"":"default ").($h{desc}?"":"desc ").($h{type}?"":"type")."\n";
}
%h = ();
}
my $state = '';
while (<>) {
print STDERR $_;
next if /^\s*$/;
if (m{^# ([a-zA-Z0-9_]+) \((.+)\)}) {
$h{param} = $1;
$h{type} = $2;
$state = 'name';
}
elsif (m{^#\s+DESC:\s+(.+)$}) {
$h{desc} = $1;
$state = 'desc';
}
elsif (m{^#\s+EXAMPLE:\s+(.+)$}) {
$h{example} = $1;
$state = 'example';
}
elsif (m{^#\s+DEFAULT:\s+(.+)$}) {
$h{default} = $1;
$state = 'default';
}
elsif (m{^#\s{0,11}(.*)$} && exists $h{desc} && $state eq 'desc') {
$h{desc} .= "\n$1";
}
elsif (m{^"([^"]+)"} && $h{param} eq $1) {
$state = '';
dumpdoc();
}
elsif (m{^# > (.+)$}) {
if (%h or $state) { die "new section '$1' but we have pending data"; }
$section = $1;
$state = 'section';
push @orderedsections, $section;
push @out, "$1\n";
push @out, "-"x(length($1))."\n\n";
}
elsif (m{^# >> (.+)$} and $state eq 'section' and $section) {
$sectiondesc{$section} = $1;
}
elsif (!/^##|^[{}]|^#\s*$/) {
die("\\--- lost here, state='$state'");
}
}
dumpdoc();
print <<EOF
======================
bastion.conf reference
======================
.. note::
The Bastion has a lot of configuration options so that you can tailor it to your needs.
However, if you're just starting and would like to get started quickly, just configure
the ``Main Options``. All the other options have sane defaults that can still be customized
at a later time.
Option List
===========
EOF
;
foreach my $section (@orderedsections) {
die "no description for section $section" if !$sectiondesc{$section};
print "\n$section\n";
print "-"x(length($section))."\n\n";
print $sectiondesc{$section}."\n\n";
foreach (@{ $sections{$section} }) {
print "- :ref:`bastion_conf_$_`\n";
}
}
print <<EOF
Option Reference
================
EOF
;
print join("", @out);

1
doc/sphinx/index.rst
View file

@ -40,6 +40,7 @@ The third section focuses on :doc:`how to use<using/index>` the bastion, from th
presentation/index
installation/index
using/index
administration/index
plugins/index
faq

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

@ -66,7 +66,7 @@ You can either use ``git clone`` directly, or get the tarball of the latest rele
- Using the tarball:
Get the tarball of the latest release, which can be found `here <https://github.com/ovh/the-bastion/releases/latest>`_, then untar it:
Get the tarball of the latest release, which can be found `there <https://github.com/ovh/the-bastion/releases/latest>`_, then untar it:
.. code-block:: shell

641
etc/bastion/bastion.conf.dist
View file

@ -1,139 +1,62 @@
############################################################################################
# Main config for The Bastion.
# This is a JSON file, its syntax must be valid at all times. To verify:
# => grep -v ^# /etc/bastion/bastion.conf|python -mjson.tool>/dev/null && echo OK
#
# If you're on a production bastion you can verify it can properly load its configuration:
# => perl -I/opt/bastion/lib/perl -MOVH::Bastion -e 'die OVH::Bastion::load_configuration()'
############################################################################################
#################################################################################################
## Main config for The Bastion.
## This is a JSON file, its syntax must be valid at all times. To verify:
## => grep -v ^# /etc/bastion/bastion.conf|python -mjson.tool>/dev/null && echo OK
##
## If you're on a production bastion you can verify it can properly load its configuration:
## => perl -I/opt/bastion/lib/perl -MOVH::Bastion -e 'OVH::Bastion::load_configuration(test=>1)'
#################################################################################################
{
################
# > Main Options
# >> Those are the options you should customize when first setting up a bastion. All the other options have sane defaults and can be customized later if needed.
#
# bastionName (string), deprecated alias: cacheName
# DESC: this will be the name advertised in the aliases admins will give to bastion users, you can see it as a friendly name everybody will use to refer to this machine (try to avoid using the full hostname here)
# DEFAULT: fix-my-config-please-missing-bastion-name
# bastionName (string)
# DESC: This will be the name advertised in the aliases admins will give to bastion users, and also in the banner of the plugins output. You can see it as a friendly name everybody will use to refer to this machine: something more friendly than just its full hostname.
# DEFAULT: "fix-my-config-please-missing-bastion-name"
"bastionName": "fix-my-config-please-missing-bastion-name",
#
# bastionCommand (string), deprecated alias: cacheCommand
# DESC: the ssh command to launch to connect to this bastion as a user. This will be printed on accountCreate, so that the new user knows how to connect. Magic values are ACCOUNT (replaced at runtime by the account name), BASTIONNAME (replaced at runtime by the name defined in `bastionName'), HOSTNAME (replaced at runtime by the hostname of the system, namely what is returned by `perl -MSys::Hostname -e 'print hostname'`). Note that previous magic values where USER (=ACCOUNT) and CACHENAME (=BASTIONNAME), they're still supported.
# DEFAULT: ssh USER@HOSTNAME -t --
# bastionCommand (string)
# DESC: The ``ssh`` command to launch to connect to this bastion as a user. This will be printed on ``accountCreate``, so that the new user knows how to connect. Magic tokens are:
#
# - ACCOUNT or USER: replaced at runtime by the account name
# - BASTIONNAME: replaced at runtime by the name defined in ``bastionName``
# - HOSTNAME: replaced at runtime by the hostname of the system
#
# So, for example if your specify ``ssh USER@HOSTNAME -t --``, it'll give ``johndoe@bastion1.example.org -t --`` as a bastion alias to *johndoe*
# DEFAULT: "ssh USER@HOSTNAME -t --"
"bastionCommand": "ssh USER@HOSTNAME -t -- ",
#
# debug (boolean-int, i.e. 0 or 1)
# DESC: enables or disables debug GLOBALLY. Discouraged. Prefer using the dev/debug_toggle.sh tool to enable/disable per account. Mostly useful for bastion developer on bastion dev machine only.
# DEFAULT: 0
"debug": 0,
# readOnlySlaveMode (boolean)
# DESC: If set to ``false``, this bastion will work in standalone mode, or will be the master in a master/slave mode. If set to ``true``, this'll be the slave which means all plugins that modify groups, accounts, or access rights will be disabled, and the master bastion will push its modifications using inotify/rsync, please refer do the documentation to set this up.
# DEFAULT: false
"readOnlySlaveMode": false,
#
# defaultLogin (string)
# DESC: The default remote user to use for egress ssh connections where no user has been specified by our caller. If set to "", will default to the account name of the caller. Some legacy bastions had "root" as a default, which is somehow discouraged but depends on your infrastructure policy.
# DEFAULT: ""
"defaultLogin": "",
#
# adminAccounts (list of accounts names), deprecated alias: adminLogins
# DESC: The list of accounts that are Admins of the bastion. Admins can't be deleted or have their ingress keys reset by non-admins. They also gain access to special dangerous/sensitive --osh commands. Note that an admin is also always considered as a Super Owner, which means they can override allchecks of group administrative commands. Don't forget to add them to the osh-admin group too, or they won't really be considered as admins (additional security measure). Rule of thumb: only add here people that have root@localhost access to the bastion
# adminAccounts (array of strings (account names))
# DESC: The list of accounts that are Admins of the bastion. Admins can't be deleted or otherwise modified by non-admins. They also gain access to special dangerous/sensitive ``--osh`` commands, such as being able to impersonate anybody else. Note that an Admin is also always considered as a Super Owner, which means they also override all checks of group administrative commands. Don't forget to add them to the ``osh-admin`` group too (system-wise), or they won't really be considered as Admins: this is an additional security measure against privilege escalation. Rule of thumb: it's probably a good idea to only add here people that have ``root`` access to the bastion machine itself.
# DEFAULT: []
"adminAccounts": [],
#
# superOwnerAccounts (list of account names)
# VALUE: list of accounts that are considered as super group owners
# DESC: The list of accounts that are considered as "Super Group Owners". They can run all group administrative commands, exactly as if they were owners of all the groups. Super Owners are only here as a last resort when the owners/gatekeepers/aclkeepers of a group are not available. Every command run by a Super Owner that would have failed if the account was not a Super Owner is logged explicitly as "Super Owner Override". You can see it as a "sudo" for group management. Don't add here accounts that are bastion Admins, they already inherit the Super Owner role.
# superOwnerAccounts (array of strings (account names))
# DESC: The list of accounts that are "Super Owners". They can run all group administrative commands, exactly as if they were implicitly owners of all the groups. Super Owners are only here as a last resort when the owners/gatekeepers/aclkeepers of a group are not available. Every command run by a Super Owner that would have failed if the account was not a Super Owner is logged explicitly as "Super Owner Override", you might want to add a rule for those in your SIEM. You can consider than the Super Owners have an implicit *sudo* for group management. Don't add here accounts that are bastion Admins, as they already inherit the Super Owner role.
# DEFAULT: []
"superOwnerAccounts": [],
#
# allowedNetworks (list of IPs and/or prefixes)
# DESC: Restricts egress connection attempts to those listed networks only. This is enforced at all times and can NOT be overridden by users. It's probably a good idea to list the prefixes of your ASN here.
# DEFAULT: empty, which means no restriction
"allowedNetworks": [],
################
# > SSH Policies
# >> All the options related to the SSH configuration and policies, both for ingress and egress connections.
#
# forbiddenNetworks (list of IPs and/or prefixes)
# DESC: Prevents egress connection to the listed networks, even if they match configured allowed networks. This can be used to prevent connection to some hosts or subnets in a broadly allowed prefix. This is enforced at all times and can NOT be overridden by users.
# DEFAULT: empty, which means no restriction
"forbiddenNetworks": [],
#
# ingressToEgressRules (array of arrays of rules, a rule being a 3-uple of {array, array, string})
# DESC: Fine-grained rules (a la netfilter) to apply global restrictions to possible egress destinations given ingress IPs. Rules here are enforced at all times and can NOT be overridden by users or admins.
# DEFAULT: [], which means no restriction
# DETAILS: A rule is a 3-uple of {array of ingress networks, array of egress networks, policy to apply}.
# Each rule will be processed IN ORDER. The first rule to match will be applied and no other rule will be checked.
# If no rule matches, the default is to apply no restriction.
# The "policy to apply" item can have 3 values:
# - ALLOW, which means that if the ingress IP matches one of the ingress networks specified in the rule, and the egress IP matches one of the egress networks specified, no restriction will be applied (all rights-check of groups and personal accesses still apply)
# - DENY, which means that if the ingress IP matches one of the ingress networks specified in the rule, and the egress IP matches one of the egress networks specified, access will be denied even before checking any group or personal accesses
# - ALLOW-EXCLUSIVE, which means that if the ingress IP matches one of the ingress networks specified in the rule, but the egress IP DOES NOT match any of the egress network specified, access will be denied. Access will still be allowed if the egress IP matches one of the egress networks specified. This is an easy way to exclusively allow a list of egress networks given a list of ingress networks, and deny any other access otherwise, for those ingress networks.
# EXAMPLE: [
# [["10.19.0.0/16","10.15.15.0/24"], ["10.20.0.0/16"], "ALLOW-EXCLUSIVE"],
# [["192.168.42.0/24"], ["192.168.42.0/24"], "ALLOW"],
# [["192.168.0.0/16"], ["192.168.0.0/16"], "DENY"]
# ]
# - The 10.19.0.0/16 and 10.15.15.0/24 networks can only access the 10.20.0.0/16 network (rule #1)
# - The 192.168.42.0/24 network can access any machine from its own /24 network (rule #2),
# but not any other machine from the wider 192.168.0.0/16 network (rule #3). It can however
# access any other machine outside of this block (implicit allow catch-all rule, as there is
# no corresponding DENY rule, and rule #2 is ALLOW and not ALLOW-EXCLUSIVE)
# - The 192.168.0.0/16 network (except 192.168.42.0/16) can access any machine except one from its own network (rule #3)
# - All the other networks can access any other network (including egress 10.20.0.0/16 or egress 192.168.0.0/16)
# In any case, all the personal and group accesses still apply in addition to these global rules
"ingressToEgressRules": [],
#
# egressKeysFrom (list of IPs and/or prefixes), deprecated alias: personalKeyFrom
# DESC: These IPs will be added to the from="..." of the personal account keys and the group keys. Typically you want to specify only the bastions IP here (including all the slaves).
# DEFAULT: if NOT set at all or set to the empty array, will default to autodetection at runtime (legacy behavior, discouraged)
"egressKeysFrom": [],
#
# ingressKeysFrom (list of IPs and/or prefixes), deprecated alias: ipWhiteList
# DESC: This array of IPs (or prefixes, such as 10.20.30.0/24) will be used to build the from="" in front of the ingress account public keys used to connect to the bastion (in accountCreate or selfAddIngressKey). If the array is empty, then NO from="" is added.
# DEFAULT: []
"ingressKeysFrom": [],
#
# ingressKeysFromAllowOverride (boolean-int, i.e. 0 or 1), aliases: ipWhiteListAllowOverride (deprecated)
# DESC: If set to 0 (false), any from="..." specified in user keys (selfAddIngressKey or accountCreate) are ignored and replaced by the IPs in the ingressKeysFrom configuration option (if any).
# If set to 1 (true), any from="..." specified in user keys (selfAddIngressKey or accountCreate) will override the value set in ingressKeysFrom (if any). When no user-specified from="..." appears, the value of ingressKeysFrom is still used, regardless of this option.
# DEFAULT: 0
"ingressKeysFromAllowOverride": 1,
#
# accountUidMin (int)
# DESC: minimum allowed UID for accounts on this bastion. Hardcoded > 1000 even if configured for less
# DEFAULT: 2000
"accountUidMin": 2000,
#
# accountUidMax (int)
# DESC: maximum allowed UID for accounts on this bastion.
# DEFAULT: 99999
"accountUidMax": 99999,
#
# ttyrecGroupIdOffset (int)
# DESC: offset to apply on user group uid to create -tty group, should be > accountUidMax
# DEFAULT: 100000
"ttyrecGroupIdOffset": 100000,
#
# accountExternalValidationProgram (path to a binary)
# DESC: Binary or script that will be called by the bastion, with the account name in parameter, to check whether this account should be allowed to connect to the bastion. If empty, this check is skipped. $BASEDIR is a magic value that is replaced by where the bastion code lives (usually, /opt/bastion). You can use this configuration parameter to counter-verify all accounts against an external system, for example an LDAP, right when they're connecting to the bastion (on the ingress side). However, it is advised to avoid calling an external system in the flow of an incoming connection (this violates the "the bastion must be working at all times, regardless of the status of the other components of the company's infrastructure" rule). Instead, you should have a cronjob to periodically fetch all the allowed accounts from said external system, and store this list somewhere on the bastion, then write a simple script that will be called by the bastion to verify whether the connecting account is present on this locally cached list. An account present in this list, is called an "active account", in the bastion's jargon. An inactive account is an account existing on the bastion, but not in this list, and won't be able to connect. Note that for security reasons, inactive bastions administrators would be denied as any other account. The result is interpreted from the program's exit code. If the program return 0, the account is deemed active. If the program returns 1, the account is deemed inactive. A return code of 2, 3 or 4 indicates a failure of the program in determining the activeness of the account. In this case, the decision to allow or deny the access is determined by the option below. Status code 3 additionally logs the stderr of the program *silently* to the syslog (this can be used to warn admins of a problem without leaking information to the user). Status code 4 does the same, but the stderr is also shown directly to the user. Any other return code deems the account inactive (same behavior that return code 1).
# DEFAULT: ""
# EXAMPLE: "$BASEDIR/bin/other/check-active-account-simple.pl"
"accountExternalValidationProgram": "",
#
# accountExternalValidationDenyOnFailure (boolean-int, aka 0 or 1)
# DESC: If we can't validate an account using the above configured program, for example because the path doesn't exist, the file is not executable, or because the program returns the exit code 4 (see above for more information), this configuration option indicates whether we should deny or allow access. Note that the bastion admins will always be allowed if the accountExternalValidationProgram doesn't work correctly, because they're expected to be able to fix it. They would be denied, as any other account, if accountExternalValidationProgram works correctly and denies them access, however. If you're still testing your account validation procedure, and don't want to break your users workflow while you're not 100% sure it works correctly, you can say 0 ("false") here, and return 4 instead of 1 in your accountExternalValidationProgram when you would want to deny access.
# DEFAULT: 1
"accountExternalValidationDenyOnFailure": 1,
#
# alwaysActiveAccounts (list of accounts)
# DESC: List of accounts which should NOT be checked against the accountExternalValidationProgram mechanism above (for example bot accounts). This can also be set per-account at account creation time or later with the accountModify plugin's '--always-active' flag.
# DEFAULT: []
"alwaysActiveAccounts": [],
#
# allowedIngressSshAlgorithms (array of algorithm names), deprecated alias: allowedSshAlgorithms
# DESC: the algorithms authorized for ingress ssh public keys added to this bastion. possible values: dsa, rsa, ecdsa, ed25519, note that some of those might not be supported by your current version of OpenSSH, unsupported algorithms are automatically omitted at runtime
# allowedIngressSshAlgorithms (array of strings (algorithm names))
# DESC: The algorithms authorized for ingress ssh public keys added to this bastion. Possible values: ``dsa``, ``rsa``, ``ecdsa``, ``ed25519``, note that some of those might not be supported by your current version of ``OpenSSH``: unsupported algorithms are automatically omitted at runtime.
# DEFAULT: [ "rsa", "ecdsa", "ed25519" ]
"allowedIngressSshAlgorithms": [ "rsa", "ecdsa", "ed25519" ],
#
# allowedEgressSshAlgorithms (array of algorithm names), deprecated alias: allowedSshAlgorithms
# aliases: allowedSshAlgorithms (deprecated)
# DESC: the algorithms authorized for egress ssh public keys generated on this bastion. possible values: dsa, rsa, ecdsa, ed25519, note that some of those might not be supported by your current version of OpenSSH, unsupported algorithms are automatically omitted at runtime
# allowedEgressSshAlgorithms (array of strings (algorithm names))
# DESC: The algorithms authorized for egress ssh public keys generated on this bastion. Possible values: ``dsa``, ``rsa``, ``ecdsa``, ``ed25519``, note that some of those might not be supported by your current version of ``OpenSSH``, unsupported algorithms are automatically omitted at runtime.
# DEFAULT: [ "rsa", "ecdsa", "ed25519" ]
"allowedEgressSshAlgorithms": [ "rsa", "ecdsa", "ed25519" ],
#
# minimumIngressRsaKeySize (int), deprecated alias: minimumRsaKeySize
# minimumIngressRsaKeySize (int)
# DESC: The minimum allowed size for ingress RSA keys (user->bastion). Sane values range from 2048 to 4096.
# DEFAULT: 2048
"minimumIngressRsaKeySize": 4096,
@ -143,7 +66,7 @@
# DEFAULT: 8192
"maximumIngressRsaKeySize": 8192,
#
# minimumEgressRsaKeySize (int), deprecated alias: minimumRsaKeySize
# minimumEgressRsaKeySize (int)
# DESC: The minimum allowed size for egress RSA keys (bastion->server). Sane values range from 2048 to 4096.
# DEFAULT: 2048
"minimumEgressRsaKeySize": 4096,
@ -154,217 +77,355 @@
"maximumEgressRsaKeySize": 8192,
#
# defaultAccountEgressKeyAlgorithm (string)
# DESC: the default algorithm to use to create the egress key of a newly created account
# DEFAULT: rsa
# DESC: The default algorithm to use to create the egress key of a newly created account
# DEFAULT: "rsa"
"defaultAccountEgressKeyAlgorithm": "rsa",
#
# defaultAccountEgressKeySize (int)
# DESC: the default size to use to create the egress key of a newly created account (also see defaultAccountEgressKeyAlgorithm)
# DESC: The default size to use to create the egress key of a newly created account (also see ``defaultAccountEgressKeyAlgorithm``)
# DEFAULT: 4096
"defaultAccountEgressKeySize": 4096,
#
# sshClientHasOptionE (boolean-int, i.e. 0 or 1)
# DESC: Set to 1 if your ssh client supports the -E option and you want to use it to log debug info on opened sessions. Discouraged, has some annoying side effects (some ssh errors then go silent from the user perspective)
# DEFAULT: 0
"sshClientHasOptionE": 0,
# moshAllowed (boolean)
# DESC: If set to ``true``, mosh usage is allowed (mosh needs to be installed on serverside, obviously). Otherwise, this feature is disabled.
# DEFAULT: false
"moshAllowed": false,
#
# sshClientDebugLevel (int, 0 to 3)
# DESC: Indicates the number of -v that will be added to the ssh client command line when starting a session. Probably a bad idea unless you want to annoy your users.
# DEFAULT: 0
"sshClientDebugLevel": 0,
#
# displayLastLogin (int)
# DESC: If != 0, display last login information on connection.
# DEFAULT: 1
"displayLastLogin": 1,
#
# accountMaxInactiveDays (int)
# DESC: If != 0, deny access to accounts that didn't log in since at least that many days. A value of 0 means that this functionality is disabled (will never deny access).
# DEFAULT: 0
"accountMaxInactiveDays": 0,
#
# accountExpiredMessage (string)
# DESC: If non-empty, customizes the message that will be printed to a user attempting to connect with an expired account (see accountMaxInactiveDays above). When empty, defaults to the standard message "Sorry, but your account has expired (#DAYS# days), access denied by policy.".
# DEFAULT: ""
"accountExpiredMessage": "",
#
# accountCreateSupplementaryGroups (array)
# DESC: List of groups to add a new account to. Can be useful to grant some restricted commands by default to new accounts. For example osh-selfAddPersonalAccess, osh-selfDelPersonalAccess, etc.
# DEFAULT: []
"accountCreateSupplementaryGroups": [],
#
# accountCreateDefaultPersonalAccesses (list of IPs and/or prefixes), deprecated alias: accountCreateDefaultPrivateAccesses
# DESC: List of strings of the form USER@IP or USER@IP:PORT or IP or IP:PORT, with IP being IP or prefix (such as 1.2.3.0/24). This is the list of accesses to add to the personal access list of newly created accounts. The special value ACCOUNT is replaced by the name of the account being created. This can be useful to grant some accesses by default to new accounts (for example ACCOUNT@0.0.0.0/0)
# DEFAULT: []
"accountCreateDefaultPersonalAccesses": [],
#
# accountMFAPolicy (enum)
# DESC: Set a MFA policy for the bastion accounts, see OPTIONS below for the supported policies list
# DEFAULT: enabled
# OPTIONS:
# disabled: the commands to setup TOTP and UNIX account password are disabled, nobody can setup MFA for himself or others. Already configured MFA still applies, unless the sshd configuration is modified to no longer call PAM on the authentication phase
# password-required: for all accounts, a UNIX account password is required in addition to the ingress SSH public key. On first connection with his SSH key, the user is forced to setup a password for his account, and can't disable it afterwards
# totp-required: for all accounts, a TOTP is required in addition to the ingress SSH public key. On first connection with his SSH key, the user is forced to setup a TOTP for his account, and can't disable it afterwards
# any-required: for all accounts, either a TOTP or an UNIX account password is required in addition to the ingress SSH public key. On first connection with his SSH key, the user is forced to setup either of those, as he sees fit, and can't disable it afterwards
# enabled: for all accounts, TOTP and UNIX account password are available as opt-in features as the users see fit. Some accounts can be forced to setup either TOTP or password-based MFA if they're flagged accordingly (with the accountModify command)
"accountMFAPolicy": "enabled",
#
# MFAPasswordMinDays (int >= 0)
# DESC: For the PAM UNIX password MFA, sets the minimum amount of days between two password changes (see `chage -m')
# DEFAULT: 0
"MFAPasswordMinDays": 0,
#
# MFAPasswordMaxDays (int >= 0)
# DESC: For the PAM UNIX password MFA, sets the maximum amount of days after which the password must be changed (see `chage -M')
# DEFAULT: 90
"MFAPasswordMaxDays": 90,
#
# MFAPasswordWarnDays (int >= 0)
# DESC: For the PAM UNIX password MFA, sets the number of days before expiration on which the user will be warned to change his password (see `chage -W')
# DEFAULT: 15
"MFAPasswordWarnDays": 15,
#
# MFAPasswordInactiveDays (int >= -1)
# DESC: For the PAM UNIX password MFA, the account will be blocked after the password is expired (and not renewed) for this amount of days (see `chage -E'). -1 disables this feature. Note that this is different from the accountMaxInactiveDays option above, that is handled by the bastion software itself instead of PAM
# DEFAULT: -1
"MFAPasswordInactiveDays": -1,
#
# MFAPostCommand (string)
# DESC: When using JIT MFA (i.e. not directly by calling PAM from SSHD's configuration, but using pamtester from within the code), execute this command on success.
# This can be used for example if you're using pam_tally2 in your PAM MFA configuration, pamtester can't reset the counter to zero because this is usually done in the account_mgmt PAM phase. You can use a script to reset it here.
# The magic value %ACCOUNT% will be replaced by the account name.
# DEFAULT: []
# EXAMPLE: ["sudo","-n","-u","root","--","/sbin/pam_tally2","-u","%ACCOUNT%","-r"],
"MFAPostCommand": [],
#
# remoteCommandEscapeByDefault (boolean-int, i.e. 0 or 1)
# DESC: If set to 0, will not escape simple quotes in remote commands by default. Leave it to 0 if possible. Will escape simple quotes otherwise (legacy "broken" behavior). Can be overridden at runtime with --never-escape and --always-escape
# DEFAULT: 0
"remoteCommandEscapeByDefault": 0,
#
# readOnlySlaveMode (boolean-int, i.e. 0 or 1)
# DESC: If set to 0, this bastion will work in standalone mode, or will be the master in a master/slave mode. If set to 1, this'll be the slave which means all plugins that modify groups, accounts, or access rights will be disabled, and the master bastion will push its modifications using inotify/rsync, please refer do the documentation to set this up
# DEFAULT: 0
"readOnlySlaveMode": 0,
#
# interactiveModeAllowed (boolean-int, i.e. 0 or 1)
# DESC: If set to 1, --interactive mode is allowed. Otherwise, this feature is disabled.
# DEFAULT: 0
"interactiveModeAllowed": 1,
#
# interactiveModeTimeout (int, in seconds)
# DESC: The number of idle seconds after which the user is disconnected from the bastion when in interactive mode. A value of 0 will disable this feature (user will never be disconnected for idle timeout)
# DEFAULT: 60
"interactiveModeTimeout": 60,
#
# interactiveModeByDefault (boolean-int)
# DESC: If true (1), drops the user to interactive mode if nothing is specified on the command line. If false (0), displays the help and exits with an error. Note that for `true' to have the expected effect, interactive mode must be enabled (see the `ìnteractiveModeAllowed' option above).
# DEFAULT: 1
"interactiveModeByDefault": 1,
#
# enableSyslog (boolean-int)
# DESC: If set to 0, syslog will be disabled. If set to 1, we'll send logs through syslog (don't forget to setup your syslogd)
# DEFAULT: 1
"enableSyslog": 1,
#
# syslogFacility (string)
# DESC: Sets the facility that will be used for syslog
# DEFAULT: local7
"syslogFacility": "local7",
#
# syslogDescription (string)
# DESC: Sets the description that will be used for syslog
# DEFAULT: bastion
"syslogDescription": "bastion",
#
# enableGlobalAccessLog (boolean-int, i.e. 0 or 1)
# DESC: If set to 1, all accesses will still be logged in the old /home/osh.log (never rotated, world-writable -> discouraged). If set to 0, we'll no longer log there (modern way is syslog, see above)
# DEFAULT: 1
"enableGlobalAccessLog": 1,
#
# enableAccountAccessLog (boolean-int, i.e. 0 or 1)
# DESC: If set to 1, all accesses will still be logged in the user's home /home/USER/USER-log-YYYYMM.log. If set to 0, we won't log there.
# DEFAULT: 1
"enableAccountAccessLog": 1,
#
# enableGlobalSqlLog (boolean-int, i.e. 0 or 1)
# DESC: If set to 1, all accesses will be logged (in a short SQL format) in /home/logkeeper/*.sqlite. If set to 0, we won't log there.
# DEFAULT: 1
"enableGlobalSqlLog": 1,
#
# enableAccountSqlLog (boolean-int, i.e. 0 or 1)
# DESC: If set to 1, all accesses will be logged (in a detailed SQL format) in the user's home /home/USER/USER-log-YYYYMM.sqlite. Otherwise, we won't log there.
# DEFAULT: 1
"enableAccountSqlLog": 1,
#
# moshAllowed (boolean-int, i.e. 0 or 1)
# DESC: If set to 1, mosh usage is allowed (mosh needs to be installed on serverside, obviously). Otherwise, this feature is disabled.
# DEFAULT: 0
"moshAllowed": 0,
#
# moshTimeoutNetwork (int, >0)
# DESC: Number of seconds of inactivity (network-wise) after a mosh-server will exit. By design even if the client is disconnected "for good", mosh-server would wait forever. If mosh is meant to handle shaky connections but not mobility, you can set this to a low value. It sets the MOSH_SERVER_NETWORK_TMOUT envvar for mosh, see `man mosh-server' for more information (mosh 1.2.6+)
# moshTimeoutNetwork (int > 0)
# DESC: Number of seconds of inactivity (network-wise) after a mosh-server will exit. By design even if the client is disconnected "for good", mosh-server would wait forever. If mosh is meant to handle shaky connections but not mobility, you can set this to a low value. It sets the ``MOSH_SERVER_NETWORK_TMOUT`` envvar for mosh, see ``man mosh-server`` for more information (mosh 1.2.6+).
# DEFAULT: 86400
"moshTimeoutNetwork": 86400,
#
# moshTimeoutSignal (int, >0)
# DESC: Number of seconds of inactivity (network-wise) a mosh-server will wait after receiving a SIGUSR1 before exiting. It sets the MOSH_SERVER_SIGNAL_TMOUT envvar for mosh, see `man mosh-server' for more information (mosh 1.2.6+)
# moshTimeoutSignal (int > 0)
# DESC: Number of seconds of inactivity (network-wise) a mosh-server will wait after receiving a ``SIGUSR1`` before exiting. It sets the ``MOSH_SERVER_SIGNAL_TMOUT`` envvar for mosh, see ``man mosh-server`` for more information (mosh 1.2.6+).
# DEFAULT: 30
"moshTimeoutSignal": 30,
#
# moshCommandLine (string)
# DESC: Additional parameters that will be passed as-is to mosh-server. See `man mosh-server', you should at least add the -p option to specify a fixed number of ports (easier for firewall configuration)
# DESC: Additional parameters that will be passed as-is to mosh-server. See ``man mosh-server``, you should at least add the ``-p`` option to specify a fixed number of ports (easier for firewall configuration).
# DEFAULT: ""
# EXAMPLE: "-s -p 40000:49999"
"moshCommandLine": "",
#
# keyboardInteractiveAllowed (boolean-int, i.e. 0 or 1)
# DESC: If set to 1, will allow keyboard-interactive authentication when publickey auth is requested for egress connections, this is needed e.g. for 2FA
# DEFAULT: 0
"keyboardInteractiveAllowed": 1,
###########################
# > Global network policies
# >> Those options can set a few global network policies to be applied bastion-wide.
#
# passwordAllowed (boolean-int, i.e. 0 or 1)
# DESC: If set to 1, will allow password authentication for egress ssh, so that user can type his remote password interactively
# DEFAULT: 0
"passwordAllowed": 0,
# allowedNetworks (array of strings (IPs and/or prefixes))
# DESC: Restricts egress connection attempts to those listed networks only. This is enforced at all times and can NOT be overridden by users. If you are lucky enough to have you own IP blocks, it's probably a good idea to list them here. An empty array means no restriction is applied.
# DEFAULT: []
# EXAMPLE: ["10.42.0.0/16","192.168.111.0/24","203.0.113.42"]
"allowedNetworks": [],
#
# telnetAllowed (boolean-int, i.e. 0 or 1)
# DESC: If set to 1, will allow telnet egress connections (-e / --telnet),
# DEFAULT: 0
"telnetAllowed": 0,
# forbiddenNetworks (array of strings (IPs and/or prefixes))
# DESC: Prevents egress connection to the listed networks, this takes precedence over ``allowedNetworks``. This can be used to prevent connection to some hosts or subnets in a broadly allowed prefix. This is enforced at all times and can NOT be overridden by users.
# DEFAULT: []
# EXAMPLE: ["10.42.42.0/24"]
"forbiddenNetworks": [],
#
# idleLockTimeout (int, >=0)
# DESC: If set to a positive value >0, the number of seconds of input idle time after which the session is locked. If 0, disabled.
# ingressToEgressRules (array of rules, a rule being a 3-uple of [array, array, string])
# DESC: Fine-grained rules (a la *netfilter*) to apply global restrictions to possible egress destinations given ingress IPs. This is similar to ``allowedNetworks`` and ``forbiddenNetworks``, but way more powerful (in fact, those two previous options can be expressed exclusively using ``ingressToEgressRules``). Those rules here are enforced at all times and can **NOT** be overridden by users or admins.
# Each rule will be processed **IN ORDER**. The first rule to match will be applied and no other rule will be checked.
# If no rule matches, the default is to apply no restriction.
# A rule is a 3-uple of [``array of ingress networks``, ``array of egress networks``, ``policy to apply``].
#
# - ``array of ingress networks``: if the IP of the ingress connection matches a network or IP in this list, the rule *may* apply: we proceed to check the egress network IP
# - ``array of egress networks``: if the IP of the egress connection matches a network or IP in this list, the rule *does* apply and we'll enforce the policy defined in the third item of the rule
# - ``policy to apply``: this is what to enforce when the ingress and egress network match
#
# The "policy to apply" item can have 3 values:
#
# - ``ALLOW``, no restriction will be applied (all rights-check of groups and personal accesses still apply)
# - ``DENY``, access will be denied regardless of any group or personal accesses
# - ``ALLOW-EXCLUSIVE``, access will be allowed **if and only if** the egress network match, given the ingress network. In other words, if the ingress IP matches one of the ingress networks specified in the rule, but the egress IP **DOES NOT** match any of the egress network specified, access will be denied. This is an easy way to ensure that a given list of ingress networks can only access a precise list of egress networks and nothing else.
#
# For example, take the following configuration:
#
# ::
#
# [
# [["10.19.0.0/16","10.15.15.0/24"], ["10.20.0.0/16"], "ALLOW-EXCLUSIVE"],
# [["192.168.42.0/24"], ["192.168.42.0/24"], "ALLOW"],
# [["192.168.0.0/16"], ["192.168.0.0/16"], "DENY"]
# ]
#
# - The ``10.19.0.0/16`` and ``10.15.15.0/24`` networks can only access the ``10.20.0.0/16`` network (rule ``#1``)
# - The ``192.168.42.0/24`` network can access any machine from its own /24 network (rule ``#2``), but not any other machine from the wider ``192.168.0.0/16`` network (rule ``#3``). It can however access any other machine outside of this block (implicit allow catch-all rule, as there is no corresponding ``DENY`` rule, and rule ``#2`` is ``ALLOW`` and not ``ALLOW-EXCLUSIVE``)
# - The ``192.168.0.0/16`` network (except ``192.168.42.0/16``) can access any machine except one from its own network (rule ``#3``)
# - All the other networks can access any other network (including egress ``10.20.0.0/16`` or egress ``192.168.0.0/16``)
#
# In any case, all the personal and group accesses still apply in addition to these global rules.
# DEFAULT: []
"ingressToEgressRules": [],
#
###########
# > Logging
# >> Options to customize how logs should be produced.
#
# enableSyslog (boolean)
# DESC: If set to ``false``, syslog will be disabled. If set to ``true``, we'll send logs through syslog (don't forget to setup your syslog daemon!).
# DEFAULT: true
"enableSyslog": true,
#
# syslogFacility (string)
# DESC: Sets the facility that will be used for syslog.
# DEFAULT: "local7"
"syslogFacility": "local7",
#
# syslogDescription (string)
# DESC: Sets the description that will be used for syslog.
# DEFAULT: "bastion"
"syslogDescription": "bastion",
#
# enableGlobalAccessLog (boolean)
# DESC: If set to ``true``, all accesses will still be logged in ``/home/osh.log``. This file is never rotated and is world writable, this is discouraged: please use syslog insteead.
# DEFAULT: true
"enableGlobalAccessLog": true,
#
# enableAccountAccessLog (boolean)
# DESC: If set to ``true``, all accesses will still be logged in the user's home ``/home/USER/USER-log-YYYYMM.log``. If set to ``false``, we won't log there.
# DEFAULT: true
"enableAccountAccessLog": true,
#
# enableGlobalSqlLog (boolean)
# DESC: If set to ``true``, all accesses will be logged (in a short SQL format) in ``/home/logkeeper/*.sqlite``. If set to ``false``, we won't log there.
# DEFAULT: true
"enableGlobalSqlLog": true,
#
# enableAccountSqlLog (boolean)
# DESC: If set to ``true``, all accesses will be logged (in a detailed SQL format) in the user's home ``/home/USER/USER-log-YYYYMM.sqlite``. Otherwise, we won't log there.
# DEFAULT: true
"enableAccountSqlLog": true,
#
# ttyrecFilenameFormat (string)
# DESC: Sets the filename format of the output files of ttyrec for a given session. Magic tokens are: ``&bastionname``, ``&uniqid``, ``&account``, ``&ip``, ``&port``, ``&user`` (they'll be replaced by the corresponding values of the current session). Then, this string (automatically prepended with the correct folder) will be passed to ttyrec's ``-F`` parameter, which uses ``strftime()`` to expand it, so the usual character conversions will be done (``%Y`` for the year, ``%H`` for the hour, etc., see ``man strftime``). Note that in a addition to the usual ``strftime()`` conversion specifications, ttyrec also supports ``#usec#``, to be replaced by the current microsecond value of the time.
# DEFAULT: "%Y-%m-%d.%H-%M-%S.#usec#.&uniqid.ttyrec"
"ttyrecFilenameFormat": "%Y-%m-%d.%H-%M-%S.#usec#.&uniqid.&account.&user.&ip.&port.ttyrec",
#
# ttyrecAdditionalParameters (array of strings)
# DESC: Additional parameters you want to pass to ``ttyrec`` invocation. Useful, for example, to enable on-the-fly compression, disable cheatcodes, or set/unset any other ``ttyrec`` option. This is an ARRAY, not a string.
# EXAMPLE: ["-s", "This is a message with spaces", "--zstd"]
# DEFAULT: []
"ttyrecAdditionalParameters": [],
#
##########################
# > Other ingress policies
# >> Policies applying to the ingress connections
#
# ingressKeysFrom (array of strings (list of IPs and/or prefixes))
# DESC: This array of IPs (or prefixes, such as ``10.20.30.0/24``) will be used to build the ``from="..."`` in front of the ingress account public keys used to connect to the bastion (in ``accountCreate`` or ``selfAddIngressKey``). If the array is empty, then **NO** ``from="..."`` is added (this lowers the security).
# DEFAULT: []
"ingressKeysFrom": [],
#
# ingressKeysFromAllowOverride (boolean)
# DESC: If set to ``false``, any user-specified ``from="..."`` prefix on keys in commands such as ``selfAddIngressKey`` or ``accountCreate`` are silently ignored and replaced by the IPs in the ``ingressKeysFrom`` configuration option (if any).
# If set to ``true``, any user-specified ``from="..."`` will override the value set in ``ingressKeysFrom`` (if any).
# Note that when no user-specified ``from="..."`` appears, the value of ``ingressKeysFrom`` is still used, regardless of this option.
# DEFAULT: true
"ingressKeysFromAllowOverride": true,
#########################
# > Other egress policies
# >> Policies applying to the egress connections
#
# defaultLogin (string)
# DESC: The default remote user to use for egress ssh connections where no user has been specified by our caller. If set to the empty string (``""``), will default to the account name of the caller. If your bastion is mainly used to connect as ``root`` on remote systems, you might want to set this to ``root`` for example, to spare a few keystrokes to your users. This is only used when no user is specified on the connection line. For example if your bastion alias is ``bssh``, and you say ``bssh srv1.example.net``, the value of the ``defaultLogin`` value will be used as the user to login as remotely.
# DEFAULT: ""
"defaultLogin": "",
#
# egressKeysFrom (array of strings (IPs and/or prefixes))
# DESC: These IPs will be added to the ``from="..."`` of the personal account keys and the group keys. Typically you want to specify only the bastions IP here (including all the slaves). Note that if this option is NOT set at all or set to the empty array, it will default to autodetection at runtime (using ``hostname --all-ip-addresses`` under the hood). This is dependent from your system configuration and is therefore discouraged.
# DEFAULT: []
"egressKeysFrom": [],
#
# keyboardInteractiveAllowed (boolean)
# DESC: If set to ``true``, will allow keyboard-interactive authentication when publickey auth is requested for egress connections, this is needed e.g. for 2FA.
# DEFAULT: true
"keyboardInteractiveAllowed": true,
#
# passwordAllowed (boolean)
# DESC: If set to ``true``, will allow password authentication for egress ssh, so that user can type his remote password interactively.
# DEFAULT: false
"passwordAllowed": false,
#
# telnetAllowed (boolean)
# DESC: If set to ``true``, will allow telnet egress connections (``-e`` / ``--telnet``).
# DEFAULT: false
"telnetAllowed": false,
#
####################
# > Session policies
# >> Options to customize the established sessions behaviour
#
# displayLastLogin (boolean)
# DESC: If ``true``, display their last login information on connection to your users.
# DEFAULT: true
"displayLastLogin": true,
#
# interactiveModeAllowed (boolean)
# DESC: If set to ``true``, ``--interactive`` mode is allowed. Otherwise, this feature is disabled.
# DEFAULT: true
"interactiveModeAllowed": true,
#
# interactiveModeTimeout (int (seconds))
# DESC: The number of idle seconds after which the user is disconnected from the bastion when in interactive mode. A value of 0 will disable this feature (user will never be disconnected for idle timeout).
# DEFAULT: 60
"interactiveModeTimeout": 60,
#
# interactiveModeByDefault (boolean)
# DESC: If ``true``, drops the user to interactive mode if nothing is specified on the command line. If ``false``, displays the help and exits with an error. Note that for ``true`` to have the expected effect, interactive mode must be enabled (see the ``interactiveModeAllowed`` option above).
# DEFAULT: true
"interactiveModeByDefault": true,
#
# idleLockTimeout (int >= 0)
# DESC: If set to a positive value >0, the number of seconds of input idle time after which the session is locked. If ``false``, disabled.
# DEFAULT: 0
"idleLockTimeout": 0,
#
# idleKillTimeout (int, >=0)
# DESC: If set to a positive value >0, the number of seconds of input idle time after which the session is killed. If 0, disabled. If idleLockTimeout is set, this value must be higher (obviously).
# idleKillTimeout (int >= 0)
# DESC: If set to a positive value >0, the number of seconds of input idle time after which the session is killed. If ``false``, disabled. If ``idleLockTimeout`` is set, this value must be higher (obviously).
# DEFAULT: 0
"idleKillTimeout": 0,
#
# warnBeforeLockSeconds (int, >=0)
# DESC: If set to a positive value >0, the number of seconds before idleLockTimeout where the user will receive a warning message telling him about the upcoming lock of his session.
# warnBeforeLockSeconds (int >= 0)
# DESC: If set to a positive value >0, the number of seconds before ``idleLockTimeout`` where the user will receive a warning message telling him about the upcoming lock of his session.
# DEFAULT: 0
"warnBeforeLockSeconds": 0,
#
# warnBeforeKillSeconds (int, >=0)
# DESC: If set to a positive value >0, the number of seconds before idleKillTimeout where the user will receive a warning message telling him about the upcoming kill of his session.
# warnBeforeKillSeconds (int >= 0)
# DESC: If set to a positive value >0, the number of seconds before ``idleKillTimeout`` where the user will receive a warning message telling him about the upcoming kill of his session.
# DEFAULT: 0
"warnBeforeKillSeconds": 0,
#
# ttyrecFilenameFormat (string)
# DESC: Sets the filename format of the output files of ttyrec for a given session. Magic tokens are: &bastionname, &uniqid, &account, &ip, &port, &user (they'll be replaced by the corresponding values of the current session). Then, this string (automatically prepended with the correct folder) will be passed to ttyrec's -F parameter, which uses strftime() to expand it, so the usual character conversions will be done (%Y for the year, %H for the hour, etc., see man strftime). Note that in a addition to the usual strftime() conversion specifications, ttyrec also supports #usec#, to be replaced by the current microsecond value of the time.
# DEFAULT: %Y-%m-%d.%H-%M-%S.#usec#.&uniqid.ttyrec
"ttyrecFilenameFormat": "%Y-%m-%d.%H-%M-%S.#usec#.&uniqid.&account.&user.&ip.&port.ttyrec",
# accountExternalValidationProgram (string (path to a binary))
# DESC: Binary or script that will be called by the bastion, with the account name in parameter, to check whether this account should be allowed to connect to the bastion. If empty, this check is skipped. ``$BASEDIR`` is a magic token that is replaced by where the bastion code lives (usually, ``/opt/bastion``).
#
# ttyrecAdditionalParameters (list of parameters)
# DESC: Additional parameters you want to pass to ttyrec invocation. Useful, for example, to enable on-the-fly compression, disable cheatcodes, or set/unset any other ttyrec option. This is an ARRAY, not a string. e.g. ["-s", "This is a message with spaces", "--zstd"]
# You can use this configuration parameter to counter-verify all accounts against an external system, for example an *LDAP*, an *Active Directory*, or any system having a list of identities, right when they're connecting to the bastion (on the ingress side). However, it is advised to avoid calling an external system in the flow of an incoming connection, as this violates the "the bastion must be working at all times, regardless of the status of the other components of the company's infrastructure" rule. Instead, you should have a cronjob to periodically fetch all the allowed accounts from said external system, and store this list somewhere on the bastion, then write a simple script that will be called by the bastion to verify whether the connecting account is present on this locally cached list.
#
# An account present in this list is called an *active account*, in the bastion's jargon. An *inactive* account is an account existing on the bastion, but not in this list, and won't be able to connect. Note that for security reasons, inactive bastions administrators would be denied as any other account.
#
# The result is interpreted from the program's exit code. If the program return 0, the account is deemed active. If the program returns 1, the account is deemed inactive. A return code of 2, 3 or 4 indicates a failure of the program in determining the activeness of the account. In this case, the decision to allow or deny the access is determined by the ``accountExternalValidationDenyOnFailure`` option below. Status code 3 additionally logs the ``stderr`` of the program *silently* to the syslog: this can be used to warn admins of a problem without leaking information to the user. Status code 4 does the same, but the ``stderr`` is also shown directly to the user. Any other return code deems the account inactive (same behavior that return code 1).
# DEFAULT: ""
# EXAMPLE: "$BASEDIR/bin/other/check-active-account-simple.pl"
"accountExternalValidationProgram": "",
#
# accountExternalValidationDenyOnFailure (boolean)
# DESC: If we can't validate an account using the program configured in ``accountExternalValidationProgram``, for example because the path doesn't exist, the file is not executable, or because the program returns the exit code 4 (see above for more information), this configuration option indicates whether we should deny or allow access.
#
# Note that the bastion admins will always be allowed if the ``accountExternalValidationProgram`` doesn't work correctly, because they're expected to be able to fix it. They would be denied, as any other account, if ``accountExternalValidationProgram`` works correctly and denies them access, however. If you're still testing your account validation procedure, and don't want to break your users workflow while you're not 100% sure it works correctly, you can say ``false`` here, and return 4 instead of 1 in your ``accountExternalValidationProgram`` when you would want to deny access.
# DEFAULT: true
"accountExternalValidationDenyOnFailure": true,
#
# alwaysActiveAccounts (array of strings (account names))
# DESC: List of accounts which should NOT be checked against the ``accountExternalValidationProgram`` mechanism above (for example bot accounts). This can also be set per-account at account creation time or later with the ``accountModify`` plugin's ``--always-active`` flag.
# DEFAULT: []
"ttyrecAdditionalParameters": [],
"alwaysActiveAccounts": [],
#
####################
# > Account policies
# >> Policies applying to the bastion accounts themselves
#
# accountMaxInactiveDays (int)
# DESC: If > 0, deny access to accounts that didn't log in since at least that many days. A value of 0 means that this functionality is disabled (we will never deny access for inactivity reasons).
# DEFAULT: 0
"accountMaxInactiveDays": 0,
#
# accountExpiredMessage (string)
# DESC: If non-empty, customizes the message that will be printed to a user attempting to connect with an expired account (see ``accountMaxInactiveDays`` above). When empty, defaults to the standard message "Sorry, but your account has expired (#DAYS# days), access denied by policy.". The special token ``#DAYS#`` is replaced by the number of days since we've last seen this user.
# DEFAULT: ""
"accountExpiredMessage": "",
#
# accountCreateSupplementaryGroups (array of strings (system group names))
# DESC: List of system groups to add a new account to when its created (see ``accountCreate``). Can be useful to grant some restricted commands by default to new accounts. For example ``osh-selfAddPersonalAccess``, ``osh-selfDelPersonalAccess``, etc. Note that the group here are **NOT** *bastion groups*, but system groups.
# DEFAULT: []
"accountCreateSupplementaryGroups": [],
#
# accountCreateDefaultPersonalAccesses (array of strings (list of IPs and/or prefixes))
# DESC: List of strings of the form USER@IP or USER@IP:PORT or IP or IP:PORT, with IP being IP or prefix (such as 1.2.3.0/24). This is the list of accesses to add to the personal access list of newly created accounts. The special value ACCOUNT is replaced by the name of the account being created. This can be useful to grant some accesses by default to new accounts (for example ACCOUNT@0.0.0.0/0)
# DEFAULT: []
"accountCreateDefaultPersonalAccesses": [],
#
# accountMFAPolicy (string)
# DESC: Set a MFA policy for the bastion accounts, the supported values are:
#
# - ``disabled``: the commands to setup TOTP and UNIX account password are disabled, nobody can setup MFA for himself or others. Already configured MFA still applies, unless the sshd configuration is modified to no longer call PAM on the authentication phase
# - ``password-required``: for all accounts, a UNIX account password is required in addition to the ingress SSH public key. On first connection with his SSH key, the user is forced to setup a password for his account, and can't disable it afterwards
# - ``totp-required``: for all accounts, a TOTP is required in addition to the ingress SSH public key. On first connection with his SSH key, the user is forced to setup a TOTP for his account, and can't disable it afterwards
# - ``any-required``: for all accounts, either a TOTP or an UNIX account password is required in addition to the ingress SSH public key. On first connection with his SSH key, the user is forced to setup either of those, as he sees fit, and can't disable it afterwards
# - ``enabled``: for all accounts, TOTP and UNIX account password are available as opt-in features as the users see fit. Some accounts can be forced to setup either TOTP or password-based MFA if they're flagged accordingly (with the accountModify command)
#
# DEFAULT: "enabled"
"accountMFAPolicy": "enabled",
#
# MFAPasswordMinDays (int >= 0)
# DESC: For the PAM UNIX password MFA, sets the min amount of days between two password changes (see ``chage -m``)
# DEFAULT: 0
"MFAPasswordMinDays": 0,
#
# MFAPasswordMaxDays (int >= 0)
# DESC: For the PAM UNIX password MFA, sets the max amount of days after which the password must be changed (see ``chage -M``)
# DEFAULT: 90
"MFAPasswordMaxDays": 90,
#
# MFAPasswordWarnDays (int >= 0)
# DESC: For the PAM UNIX password MFA, sets the number of days before expiration on which the user will be warned to change his password (see ``chage -W``)
# DEFAULT: 15
"MFAPasswordWarnDays": 15,
#
# MFAPasswordInactiveDays (int >= -1)
# DESC: For the PAM UNIX password MFA, the account will be blocked after the password is expired (and not renewed) for this amount of days (see ``chage -E``). -1 disables this feature. Note that this is different from the accountMaxInactiveDays option above, that is handled by the bastion software itself instead of PAM
# DEFAULT: -1
"MFAPasswordInactiveDays": -1,
#
# MFAPostCommand (array of strings (a valid system command))
# DESC: When using JIT MFA (i.e. not directly by calling PAM from SSHD's configuration, but using ``pamtester`` from within the code), execute this command on success.
# This can be used for example if you're using ``pam_tally2`` in your PAM MFA configuration, ``pamtester`` can't reset the counter to zero because this is usually done in the ``account_mgmt`` PAM phase. You can use a script to reset it here.
# The magic token ``%ACCOUNT%`` will be replaced by the account name.
# DEFAULT: []
# EXAMPLE: ["sudo","-n","-u","root","--","/sbin/pam_tally2","-u","%ACCOUNT%","-r"],
"MFAPostCommand": [],
#
#################
# > Other options
# >> These options are either discouraged (in which case this is explained in the description) or rarely need to be modified.
#
# accountUidMin (int)
# DESC: Minimum allowed UID for accounts on this bastion. Hardcoded > 100 even if configured for less.
# DEFAULT: 2000
"accountUidMin": 2000,
#
# accountUidMax (int)
# DESC: Maximum allowed UID for accounts on this bastion.
# DEFAULT: 99999
"accountUidMax": 99999,
#
# ttyrecGroupIdOffset (int)
# DESC: Offset to apply on user group uid to create its ``-tty`` group, should be > ``accountUidMax - accountUidMin`` to ensure there is no overlap.
# DEFAULT: 100000
"ttyrecGroupIdOffset": 100000,
#
# documentationURL (string)
# DESC: The URL of the documentation where users will be pointed to, for example when displaying help. If you have some internal documentation about the bastion, you might want to advertise it here.
# DEFAULT: "https://ovh.github.io/the-bastion/"
"documentationURL": "https://ovh.github.io/the-bastion/"
#
# debug (boolean)
# DESC: Enables or disables debug *GLOBALLY*, printing a lot of information to anyone using the bastion. Don't enable this unless you're chasing a bug in the code and are familiar with it.
# DEFAULT: false
"debug": false,
#
# remoteCommandEscapeByDefault (boolean)
# DESC: If set to ``false``, will not escape simple quotes in remote commands by default. Don't enable this, this is to keep compatibility with an ancient broken behavior. Will be removed in the future. Can be overridden at runtime with ``--never-escape`` and ``--always-escape``.
# DEFAULT: false
"remoteCommandEscapeByDefault": false,
#
# sshClientDebugLevel (int (0-3))
# DESC: Indicates the number of ``-v``'s that will be added to the ssh client command line when starting a session. Probably a bad idea unless you want to annoy your users.
# DEFAULT: 0
"sshClientDebugLevel": 0,
#
# sshClientHasOptionE (boolean)
# DESC: Set to ``true`` if your ssh client supports the ``-E`` option and you want to use it to log debug info on opened sessions. **Discouraged** because it has some annoying side effects (some ssh errors then go silent from the user perspective).
# DEFAULT: false
"sshClientHasOptionE": false,
}