commit 4317b3a5291b7d971a41cf1588e4be100b03e8e3 Author: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue Sep 17 12:46:21 2024 +0000 Deploy to GitHub pages diff --git a/.buildinfo b/.buildinfo new file mode 100644 index 0000000..7b14034 --- /dev/null +++ b/.buildinfo @@ -0,0 +1,4 @@ +# Sphinx build info version 1 +# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. +config: 219f4083df119dbc63e42c5077c45e34 +tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/_images/group_roles.png b/_images/group_roles.png new file mode 100644 index 0000000..f8c176d Binary files /dev/null and b/_images/group_roles.png differ diff --git a/_images/groups.png b/_images/groups.png new file mode 100644 index 0000000..7e630da Binary files /dev/null and b/_images/groups.png differ diff --git a/_images/locked_session.png b/_images/locked_session.png new file mode 100644 index 0000000..104c5bf Binary files /dev/null and b/_images/locked_session.png differ diff --git a/_images/putty1.png b/_images/putty1.png new file mode 100644 index 0000000..b107bf2 Binary files /dev/null and b/_images/putty1.png differ diff --git a/_images/putty10.png b/_images/putty10.png new file mode 100644 index 0000000..ebfd243 Binary files /dev/null and b/_images/putty10.png differ diff --git a/_images/putty2.png b/_images/putty2.png new file mode 100644 index 0000000..73f4c51 Binary files /dev/null and b/_images/putty2.png differ diff --git a/_images/putty3.png b/_images/putty3.png new file mode 100644 index 0000000..dbdbb6d Binary files /dev/null and b/_images/putty3.png differ diff --git a/_images/putty4.png b/_images/putty4.png new file mode 100644 index 0000000..68ee93e Binary files /dev/null and b/_images/putty4.png differ diff --git a/_images/putty5.png b/_images/putty5.png new file mode 100644 index 0000000..56b25d1 Binary files /dev/null and b/_images/putty5.png differ diff --git a/_images/putty6.png b/_images/putty6.png new file mode 100644 index 0000000..f0b333c Binary files /dev/null and b/_images/putty6.png differ diff --git a/_images/putty7.png b/_images/putty7.png new file mode 100644 index 0000000..a685172 Binary files /dev/null and b/_images/putty7.png differ diff --git a/_images/putty8.png b/_images/putty8.png new file mode 100644 index 0000000..81a6110 Binary files /dev/null and b/_images/putty8.png differ diff --git a/_images/putty9.png b/_images/putty9.png new file mode 100644 index 0000000..491fa9b Binary files /dev/null and b/_images/putty9.png differ diff --git a/_sources/administration/configuration/bastion_conf.rst.txt b/_sources/administration/configuration/bastion_conf.rst.txt new file mode 100644 index 0000000..c1bc155 --- /dev/null +++ b/_sources/administration/configuration/bastion_conf.rst.txt @@ -0,0 +1,1042 @@ +============ +bastion.conf +============ + + .. note:: + + The Bastion has a lot of configuration options so that you can tailor it + to your needs. However, if you're just beggining 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 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`_ +- `bastionCommand`_ +- `readOnlySlaveMode`_ +- `adminAccounts`_ +- `superOwnerAccounts`_ + +SSH Policies options +-------------------- + +All the options related to the SSH configuration and policies, both for ingress and egress connections. + +- `allowedIngressSshAlgorithms`_ +- `allowedEgressSshAlgorithms`_ +- `minimumIngressRsaKeySize`_ +- `maximumIngressRsaKeySize`_ +- `minimumEgressRsaKeySize`_ +- `maximumEgressRsaKeySize`_ +- `defaultAccountEgressKeyAlgorithm`_ +- `defaultAccountEgressKeySize`_ +- `moshAllowed`_ +- `moshTimeoutNetwork`_ +- `moshTimeoutSignal`_ +- `moshCommandLine`_ + +Global network policies options +------------------------------- + +Those options can set a few global network policies to be applied bastion-wide. + +- `dnsSupportLevel`_ +- `allowedNetworks`_ +- `forbiddenNetworks`_ +- `ingressToEgressRules`_ + +Logging options +--------------- + +Options to customize how logs should be produced. + +- `enableSyslog`_ +- `syslogFacility`_ +- `syslogDescription`_ +- `enableGlobalAccessLog`_ +- `enableAccountAccessLog`_ +- `enableGlobalSqlLog`_ +- `enableAccountSqlLog`_ +- `ttyrecFilenameFormat`_ +- `ttyrecAdditionalParameters`_ +- `ttyrecStealthStdoutPattern`_ + +Other ingress policies options +------------------------------ + +Policies applying to the ingress connections + +- `ingressKeysFrom`_ +- `ingressKeysFromAllowOverride`_ + +Other egress policies options +----------------------------- + +Policies applying to the egress connections + +- `defaultLogin`_ +- `egressKeysFrom`_ +- `keyboardInteractiveAllowed`_ +- `passwordAllowed`_ +- `telnetAllowed`_ + +Session policies options +------------------------ + +Options to customize the established sessions behaviour + +- `displayLastLogin`_ +- `fanciness`_ +- `interactiveModeAllowed`_ +- `interactiveModeTimeout`_ +- `interactiveModeByDefault`_ +- `interactiveModeProactiveMFAenabled`_ +- `interactiveModeProactiveMFAexpiration`_ +- `idleLockTimeout`_ +- `idleKillTimeout`_ +- `warnBeforeLockSeconds`_ +- `warnBeforeKillSeconds`_ +- `accountExternalValidationProgram`_ +- `accountExternalValidationDenyOnFailure`_ +- `alwaysActiveAccounts`_ + +Account policies options +------------------------ + +Policies applying to the bastion accounts themselves + +- `accountMaxInactiveDays`_ +- `accountExpiredMessage`_ +- `accountCreateSupplementaryGroups`_ +- `accountCreateDefaultPersonalAccesses`_ +- `ingressRequirePIV`_ +- `accountMFAPolicy`_ +- `MFAPasswordMinDays`_ +- `MFAPasswordMaxDays`_ +- `MFAPasswordWarnDays`_ +- `MFAPasswordInactiveDays`_ +- `MFAPostCommand`_ +- `TOTPProvider`_ + +Other options options +--------------------- + +These options are either discouraged (in which case this is explained in the description) or rarely need to be modified. + +- `accountUidMin`_ +- `accountUidMax`_ +- `ttyrecGroupIdOffset`_ +- `documentationURL`_ +- `debug`_ +- `remoteCommandEscapeByDefault`_ +- `sshClientDebugLevel`_ +- `sshClientHasOptionE`_ + +Option Reference +================ + +Main Options +------------ + +.. _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. + +.. _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* + +.. _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. + +.. _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. + +.. _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. Don't forget to add them to the ``osh-superowner`` group too (system-wise), or they won't really be considered as "Super Owners": this is an additional security measure against privilege escalation. + +SSH Policies +------------ + +.. _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: ``rsa``, ``ecdsa``, ``ed25519``, ``ecdsa-sk``, ``ed25519-sk``, note that some of those might not be supported by your current version of ``OpenSSH``: unsupported algorithms are automatically omitted at runtime. + +.. _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: ``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. + +.. _minimumIngressRsaKeySize: + +minimumIngressRsaKeySize +************************ + +:Type: ``int > 0`` + +:Default: ``2048`` + +The minimum allowed size for ingress RSA keys (user->bastion). Sane values range from 2048 to 4096. + +.. _maximumIngressRsaKeySize: + +maximumIngressRsaKeySize +************************ + +:Type: ``int > 0`` + +: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. + +.. _minimumEgressRsaKeySize: + +minimumEgressRsaKeySize +*********************** + +:Type: ``int > 0`` + +:Default: ``2048`` + +The minimum allowed size for egress RSA keys (bastion->server). Sane values range from 2048 to 4096. + +.. _maximumEgressRsaKeySize: + +maximumEgressRsaKeySize +*********************** + +:Type: ``int > 0`` + +: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. + +.. _defaultAccountEgressKeyAlgorithm: + +defaultAccountEgressKeyAlgorithm +******************************** + +:Type: ``string`` + +:Default: ``"rsa"`` + +The default algorithm to use to create the egress key of a newly created account + +.. _defaultAccountEgressKeySize: + +defaultAccountEgressKeySize +*************************** + +:Type: ``int > 0`` + +:Default: ``4096`` + +The default size to use to create the egress key of a newly created account (also see ``defaultAccountEgressKeyAlgorithm``) + +.. _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. + +.. _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+). + +.. _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+). + +.. _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 +----------------------- + +.. _dnsSupportLevel: + +dnsSupportLevel +*************** + +:Type: ``integer between 0 and 2`` + +:Default: ``2`` + +If set to 0, The Bastion will never attempt to do DNS or reverse-DNS resolutions, and return an error if you request connection to a hostname instead of an IP. Use this if you know there's no working DNS in your environment and only use IPs everywhere. + If set to 1, The Bastion will not attempt to do DNS or reverse-DNS resolutions unless you force it to (i.e. by requesting connection to a hostname instead of an IP). You may use this if for example you have well-known hostnames in /etc/hosts, but don't have a working DNS (which would imply that reverse-DNS resolutions will always fail). + If set to 2, The Bastion will make the assumption that you have a working DNS setup, and will do DNS and reverse-DNS resolutions normally. + +.. _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. + +.. _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. + +.. _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 +------- + +.. _enableSyslog: + +enableSyslog +************ + +:Type: ``boolean`` + +:Default: ``true`` + +If enabled, we'll send logs through syslog, don't forget to setup your syslog daemon!. You can also adjust ``syslogFacility`` and ``syslogDescription`` below, to match your syslog configuration. Note that the provided ``syslog-ng`` templates work with the default values left as-is. + +.. _syslogFacility: + +syslogFacility +************** + +:Type: ``string`` + +:Default: ``"local7"`` + +Sets the facility that will be used for syslog. + +.. _syslogDescription: + +syslogDescription +***************** + +:Type: ``string`` + +:Default: ``"bastion"`` + +Sets the description that will be used for syslog. + +.. _enableGlobalAccessLog: + +enableGlobalAccessLog +********************* + +:Type: ``boolean`` + +:Default: ``true`` + +If enabled, all *open* and *close* logs will be written to ``/home/logkeeper/global-log-YYYYMM.log``. Those are also logged through syslog if *enableSyslog* is set. + +.. _enableAccountAccessLog: + +enableAccountAccessLog +********************** + +:Type: ``boolean`` + +:Default: ``true`` + +If enabled, all *open* and *close* logs will be written to the corresponding user's home in ``/home/USER/USER-log-YYYYMM.log``. Those are also logged through syslog if *enableSyslog* is set. + +.. _enableGlobalSqlLog: + +enableGlobalSqlLog +****************** + +:Type: ``boolean`` + +:Default: ``true`` + +If enabled, all access logs (corresponding to the *open* and *close* events) will be written in a short SQL format, as one row per access, to ``/home/logkeeper/global-log-YYYYMM.sqlite``. + +.. _enableAccountSqlLog: + +enableAccountSqlLog +******************* + +:Type: ``boolean`` + +:Default: ``true`` + +If enabled, all access logs (corresponding to the *open* and *close* events) will be written in a detailed SQL format, as one row per access, in the corresponding user's home to ``/home/USER/USER-log-YYYYMM.sqlite``. If you want to use ``selfListSessions`` and/or ``selfPlaySession``, this is required. + +.. _ttyrecFilenameFormat: + +ttyrecFilenameFormat +******************** + +:Type: ``string`` + +:Default: ``"%Y-%m-%d.%H-%M-%S.#usec#.&uniqid.&account.&user.&ip.&port.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. + +.. _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. + +.. _ttyrecStealthStdoutPattern: + +ttyrecStealthStdoutPattern +************************** + +:Type: ``regex`` + +:Default: ``""`` + +:Example: ``"^rsync --server .+"`` + +When this is set to a non-falsy value, this is expected to be a string that will be converted to a regex which will be matched against a potential remote command specified when connecting through SSH to a remote server. If the regex matches, then we'll instruct ttyrec to NOT record stdout for this session. + +Other ingress policies +---------------------- + +.. _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). + +.. _ingressKeysFromAllowOverride: + +ingressKeysFromAllowOverride +**************************** + +:Type: ``boolean`` + +:Default: ``false`` + +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 +--------------------- + +.. _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. + +.. _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. + +.. _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. + +.. _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. + +.. _telnetAllowed: + +telnetAllowed +************* + +:Type: ``boolean`` + +:Default: ``false`` + +If set to ``true``, will allow telnet egress connections (``-e`` / ``--telnet``). + +Session policies +---------------- + +.. _displayLastLogin: + +displayLastLogin +**************** + +:Type: ``boolean`` + +:Default: ``true`` + +If ``true``, display their last login information on connection to your users. + +.. _fanciness: + +fanciness +********* + +:Type: ``string`` + +:Default: ``full`` + +Customize to which extent the text output by the program will use decorations to enhance human-friendliness and highlight warnings or critical messages. Note that if a given session's terminal doesn't advertise UTF-8 support, UTF-8 will not be used, regardless of what is set here. + +- "none": Text will only consist of us-ascii characters +- "basic": UTF-8 characters will be used to draw tables, instead of ---'s, among other things +- "full": Some emoticons may appear to highlight important messages + +.. _interactiveModeAllowed: + +interactiveModeAllowed +********************** + +:Type: ``boolean`` + +:Default: ``true`` + +If set to ``true``, ``--interactive`` mode is allowed. Otherwise, this feature is disabled. + +.. _interactiveModeTimeout: + +interactiveModeTimeout +********************** + +:Type: ``int >= 0 (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). + +.. _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). + +.. _interactiveModeProactiveMFAenabled: + +interactiveModeProactiveMFAenabled +********************************** + +:Type: ``boolean`` + +:Default: ``true`` + +If enabled, the ``mfa`` command is allowed in interactive mode, to trigger a proactive MFA challenge, so that subsequent commands normally requiring MFA won't ask for it again. + +.. _interactiveModeProactiveMFAexpiration: + +interactiveModeProactiveMFAexpiration +************************************* + +:Type: ``int >= 0 (seconds)`` + +:Default: ``900`` + +If the above ``interactiveModeProactiveMFAenabled`` option is ``true``, then this is the amount of seconds after which the proactive MFA mode is automatically disengaged. + +.. _idleLockTimeout: + +idleLockTimeout +*************** + +:Type: ``int >= 0 (seconds)`` + +: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. + +.. _idleKillTimeout: + +idleKillTimeout +*************** + +:Type: ``int >= 0 (seconds)`` + +: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). + +.. _warnBeforeLockSeconds: + +warnBeforeLockSeconds +********************* + +:Type: ``int >= 0 (seconds)`` + +:Default: ``0`` + +If set to a positive value >0, the number of seconds before ``idleLockTimeout`` where the user will receive a warning message telling them about the upcoming lock of his session. Don't enable this (by setting a non-zero value) if `idleLockTimeout` is disabled (set to zero). + +.. _warnBeforeKillSeconds: + +warnBeforeKillSeconds +********************* + +:Type: ``int >= 0 (seconds)`` + +:Default: ``0`` + +If set to a positive value >0, the number of seconds before ``idleKillTimeout`` where the user will receive a warning message telling them about the upcoming kill of his session. Don't enable this (by setting a non-zero value) if `idleKillTimeout` is disabled (set to zero). + +.. _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). + +.. _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. + +.. _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 +---------------- + +.. _accountMaxInactiveDays: + +accountMaxInactiveDays +********************** + +:Type: ``int >= 0 (days)`` + +: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). + +.. _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. + +.. _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. + +.. _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) + +.. _ingressRequirePIV: + +ingressRequirePIV +***************** + +:Type: ``boolean`` + +:Default: ``false`` + +When set to true, only PIV-enabled SSH keys will be able to be added with selfAddIngressKey, hence ensuring that an SSH key generated on a computer, and not within a PIV-compatible hardware token, can't be used to access The Bastion. If you only want to enable this on a per-account basis, leave this to false and set the flag on said accounts using accountPIV instead. When set to false, will not require PIV-enabled SSH keys to be added by selfAddIngressKey. If you have no idea what PIV keys are, leave this to false, this is what you want. + +.. _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 themselves 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) + + +.. _MFAPasswordMinDays: + +MFAPasswordMinDays +****************** + +:Type: ``int >= 0 (days)`` + +:Default: ``0`` + +For the PAM UNIX password MFA, sets the min amount of days between two password changes (see ``chage -m``) + +.. _MFAPasswordMaxDays: + +MFAPasswordMaxDays +****************** + +:Type: ``int >= 0 (days)`` + +:Default: ``90`` + +For the PAM UNIX password MFA, sets the max amount of days after which the password must be changed (see ``chage -M``) + +.. _MFAPasswordWarnDays: + +MFAPasswordWarnDays +******************* + +:Type: ``int >= 0 (days)`` + +: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``) + +.. _MFAPasswordInactiveDays: + +MFAPasswordInactiveDays +*********************** + +:Type: ``int >= -1 (days)`` + +: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 + +.. _MFAPostCommand: + +MFAPostCommand +************** + +:Type: ``array of strings (a valid system command)`` + +:Default: ``[]`` + +:Example: ``["sudo","-n","-u","root","--","/sbin/pam_tally2","-u","%ACCOUNT%","-r"] or ["/usr/sbin/faillock","--reset"]`` + +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`` or ``pam_faillock`` 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. +Note that usually, ``pam_tally2`` can only be used by root (hence might require the proper sudoers configuration), while ``faillock`` can directly be used by unprivileged users to reset their counter. + +.. _TOTPProvider: + +TOTPProvider +************ + +:Type: ``string`` + +:Default: ``'google-authenticator'`` + +Defines which is the provider of the TOTP MFA, that will be used for the ``(self|account)MFA(Setup|Reset)TOTP`` commands. Allowed values are: +- none: no TOTP providers are defined, the corresponding setup commands won't be available. +- google-authenticator: the pam_google_authenticator.so module will be used, along with its corresponding setup binary. This is the default, for backward compatibility reasons. This is also what is configured in the provided pam templates. +- duo: enable the use of the Duo PAM module (pam_duo.so), of course you need to set it up correctly in your `/etc/pam.d/sshd` file. + +Other options +------------- + +.. _accountUidMin: + +accountUidMin +************* + +:Type: ``int >= 100`` + +:Default: ``2000`` + +Minimum allowed UID for accounts on this bastion. Hardcoded > 100 even if configured for less. + +.. _accountUidMax: + +accountUidMax +************* + +:Type: ``int > 0`` + +:Default: ``99999`` + +Maximum allowed UID for accounts on this bastion. + +.. _ttyrecGroupIdOffset: + +ttyrecGroupIdOffset +******************* + +:Type: ``int > 0`` + +:Default: ``100000`` + +Offset to apply on user group uid to create its ``-tty`` group, should be > ``accountUidMax - accountUidMin`` to ensure there is no overlap. + +.. _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. + +.. _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. + +.. _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``. + +.. _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. + +.. _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). + diff --git a/_sources/administration/configuration/index.rst.txt b/_sources/administration/configuration/index.rst.txt new file mode 100644 index 0000000..235ebe2 --- /dev/null +++ b/_sources/administration/configuration/index.rst.txt @@ -0,0 +1,36 @@ +=================== +Configuration files +=================== + +Main configuration files +======================== + +These config files should be reviewed and adapted for the environment in which +you're deploying The Bastion. The doc:`bastion_conf` is the only one that is +mandatory to get you started. You should however review the other ones before +going into production. + +.. toctree:: + :maxdepth: 1 + + bastion_conf + osh-backup-acl-keys_conf + osh-encrypt-rsync_conf + osh-sync-watcher_sh + osh-http-proxy_conf + +Configuration files for satellite scripts +========================================= + +These config files govern the behavior of satellite scripts that handle +background tasks of The Bastion. Most of the time, there is no need to alter +the configuration as sane defaults are already built in. + +.. toctree:: + :maxdepth: 1 + + osh-piv-grace-reaper_conf + osh-remove-empty-folders_conf + osh-cleanup-guest-key-access_conf + osh-lingering-sessions-reaper_conf + osh-orphaned-homedir_conf diff --git a/_sources/administration/configuration/osh-backup-acl-keys_conf.rst.txt b/_sources/administration/configuration/osh-backup-acl-keys_conf.rst.txt new file mode 100644 index 0000000..720b257 --- /dev/null +++ b/_sources/administration/configuration/osh-backup-acl-keys_conf.rst.txt @@ -0,0 +1,183 @@ +======================== +osh-backup-acl-keys.conf +======================== + + .. note:: + + This script is called by cron and is responsible + for backing up the bastion configuration, users & groups lists, + credentials, and everything needed to be able to restore a functioning + bastion from scratch. + + .. warning:: + + If left unconfigured, this script won't do anything, + and you won't have backups, unless this task is handled by + some other external system. + +Option List +=========== + +Logging & activation options +---------------------------- + +Script logging configuration and script activation + +- `LOGFILE`_ +- `LOG_FACILITY`_ +- `ENABLED`_ + +Backup policy options +--------------------- + +These options configure the backup policy to apply + +- `DESTDIR`_ +- `DAYSTOKEEP`_ + +Encryption and signing options +------------------------------ + +These options configure how the script uses GPG to encrypt and sign the ttyrec files + +- `GPGKEYS`_ +- `SIGNING_KEY`_ +- `SIGNING_KEY_PASSPHRASE`_ + +Remote backup options +--------------------- + +These options configure how the script should push the encrypted backups to a remote system + +- `PUSH_REMOTE`_ +- `PUSH_OPTIONS`_ + +Option Reference +================ + +Logging & activation +-------------------- + +LOGFILE +******* + +:Type: ``string, path to a file`` + +:Default: ``""`` + +File where the logs will be written to (don't forget to configure ``logrotate``!). +Note that using this configuration option, the script will directly write to the file, without using syslog. +If empty, won't log directly to any file. + +LOG_FACILITY +************ + +:Type: ``string`` + +:Default: ``"local6"`` + +The syslog facility to use for logging the script output. +If set to the empty string, we'll not log through syslog at all. +If this configuration option is missing from your config file altogether, +the default value will be used (local6), which means that we'll log to syslog. + +ENABLED +******* + +:Type: ``0 or 1`` + +:Default: ``1`` + +If set to 1, the script is enabled and will run when started by crond. + +Backup policy +------------- + +DESTDIR +******* + +:Type: ``path to a folder`` + +:Default: ``""`` + +:Example: ``"/root/backups"`` + +Folder where to put the backup artefacts (``.tar.gz`` files). +This folder will be created if needed. If empty or omitted, +the script won't run: this option is mandatory. + +DAYSTOKEEP +********** + +:Type: ``int > 0`` + +:Default: ``90`` + +Number of days to keep the old backups on the filesystem before deleting them. + +Encryption and signing +---------------------- + +GPGKEYS +******* + +:Type: ``string, space-separated list of GPG keys IDs`` + +:Default: ``""`` + +:Example: ``"41FDB9C7 DA97EFD1 339483FF"`` + +List of public GPG keys to encrypt to (see ``gpg --list-keys``), these must be separated by spaces. +Note that if this option is empty or omitted, backup artefacts will NOT be encrypted! + +SIGNING_KEY +*********** + +:Type: ``string, GPG key ID in short or long format`` + +:Default: ``(none)`` + +ID of the GPG key used to sign the ttyrec files. +The key must be in the local root keyring, check it with ``gpg --list-secret-keys``. +If empty, the archives will not be signed, but encrypted only (using the GPGKEYS configuration above). + +SIGNING_KEY_PASSPHRASE +********************** + +:Type: ``string`` + +:Default: ``(none)`` + +This passphrase should be able to unlock the SIGNING_KEY defined above. +Please ensure this configuration file only readable by root (0640), to protect this passphrase. +As a security measure, the script will refuse to read the configuration otherwise. + +Remote backup +------------- + +PUSH_REMOTE +*********** + +:Type: ``string`` + +:Default: ``""`` + +:Example: ``"push@192.0.2.4:~/backup/"`` + +The ``scp`` remote host push backups to. If empty or missing, won't push backups. +This will also be the case if the ``GPGKEYS`` option above is empty or missing, +because we will never push unencrypted backups. +Don't forget to put a trailing ``/`` (except if you want to push to the remote ``$HOME``, +in which case ending with a simple ``:`` works, as per standard ``scp``). + +PUSH_OPTIONS +************ + +:Type: ``string`` + +:Default: ``""`` + +:Example: ``"-i $HOME/.ssh/id_backup"`` + +Additional options to pass to ``scp``, if needed. + diff --git a/_sources/administration/configuration/osh-cleanup-guest-key-access_conf.rst.txt b/_sources/administration/configuration/osh-cleanup-guest-key-access_conf.rst.txt new file mode 100644 index 0000000..b4cb7d3 --- /dev/null +++ b/_sources/administration/configuration/osh-cleanup-guest-key-access_conf.rst.txt @@ -0,0 +1,51 @@ +================================= +osh-cleanup-guest-key-access.conf +================================= + + .. note:: + + This script is called by cron and is responsible for cleaning up dangling + accesses to group keys for group guests that no longer have access to any + server of the group. This happens when the last access a guest have on a + group has a TTL, and this TTL expires. + This is a basic background task of The Bastion, hence there is not much + to configure. You can still disable this script below, if needs be. + +Option List +=========== + +Logging & activation options +---------------------------- + +Script logging configuration and script activation + +- `syslog_facility`_ +- `enabled`_ + +Option Reference +================ + +Logging & activation +-------------------- + +syslog_facility +*************** + +:Type: ``string`` + +:Default: ``local6`` + +The syslog facility to use for logging the script output. +If set to the empty string, we'll not log through syslog at all. +If this configuration option is missing from your config file altogether, +the default value will be used (local6), which means that we'll log to syslog. + +enabled +******* + +:Type: ``bool`` + +:Default: ``true`` + +If not set to `true` (or a true value), the script will not run. + diff --git a/_sources/administration/configuration/osh-encrypt-rsync_conf.rst.txt b/_sources/administration/configuration/osh-encrypt-rsync_conf.rst.txt new file mode 100644 index 0000000..0cfdd31 --- /dev/null +++ b/_sources/administration/configuration/osh-encrypt-rsync_conf.rst.txt @@ -0,0 +1,243 @@ +====================== +osh-encrypt-rsync.conf +====================== + +.. note:: + + The osh-encrypt-rsync script is called by cron and is responsible for encrypting + and optionally pushing the recorded ``ttyrec`` files to a distant server, along + with the user logs (``/home/*/*.log``) and user sqlite files (``/home/*/*.sqlite``). + The global log and sqlite files are also handled (located in ``/home/logkeeper/``). + Note that logs sent through syslog are NOT managed by this script. + +.. warning:: + + If left unconfigured, this script won't do anything, and the recorded ``ttyrec`` files, + along with the log and sqlite files won't be encrypted or moved out from the server. + This might not be a problem for low-traffic bastions or if you have plenty of storage available, though. + +Option List +=========== + +Logging options +--------------- + +These options configure the way the script logs its actions + +- `logfile`_ +- `syslog_facility`_ +- `verbose`_ + +Encryption and signing options +------------------------------ + +These options configure how the script uses GPG to encrypt and sign the ttyrec files + +- `signing_key`_ +- `signing_key_passphrase`_ +- `recipients`_ +- `encrypt_and_move_to_directory`_ +- `encrypt_and_move_ttyrec_delay_days`_ +- `encrypt_and_move_user_logs_delay_days`_ +- `encrypt_and_move_user_sqlites_delay_days`_ + +Push files to a remote destination options +------------------------------------------ + +These options configure the way the script uses rsync to optionally push the encrypted files out of the server + +- `rsync_destination`_ +- `rsync_rsh`_ +- `rsync_delay_before_remove_days`_ + +Option Reference +================ + +Logging +------- + +logfile +******* + +:Type: ``string, path to a file`` + +:Default: ``""`` + +File where the logs will be written to (don't forget to configure ``logrotate``!). +Note that using this configuration option, the script will directly write to the file, without using syslog. +If empty, won't log directly to any file. + +syslog_facility +*************** + +:Type: ``string`` + +:Default: ``"local6"`` + +The syslog facility to use for logging the script output. +If set to the empty string, we'll not log through syslog at all. +If this configuration option is missing from your config file altogether, +the default value will be used (local6), which means that we'll log to syslog. + +verbose +******* + +:Type: ``int >= 0`` + +:Default: ``0`` + +The verbosity level of the logs produced by the script +0: normal (default) +1: log more information about what is happening +2: log debug-level information + +Encryption and signing +---------------------- + +signing_key +*********** + +:Type: ``string, GPG key ID in short or long format`` + +:Default: ``(none), setting a value is mandatory`` + +ID of the GPG key used to sign the ttyrec files. +The key must be in the local root keyring, check it with ``gpg --list-secret-keys`` + +signing_key_passphrase +********************** + +:Type: ``string`` + +:Default: ``(none), setting a value is mandatory`` + +This passphrase should be able to unlock the ``signing_key`` defined above. +As a side note, please ensure this configuration file only readable by root (0640), +to protect this passphrase. As a security measure, +the script will refuse to read the configuration otherwise. + +recipients +********** + +:Type: ``array of array of strings, a string being a GPG key ID in short or long format`` + +:Default: ``(none), setting a value is mandatory`` + +The ttyrecs will be encrypted with those GPG keys, possibly using multi-layer GPG encryption. +Each sub-array is a layer, the first sub-array being the first encryption layer (which is also the last one for decryption) +To completely decrypt a ttyrec, one would need at least one key of each layer. +To encrypt only to a single layer and to only one key, simply use [ [ "KEYID" ] ]. +To encrypt to a single layer but with 3 keys being able to decrypt the ttyrec, use [ [ "KEY1", "KEY2", "KEY3" ] ], etc. +A common use of multi-layer encryption is to have the first layer composed of the auditors' GPG keys, and +the second layer composed of the sysadmins' GPG keys. During an audit, the sysadmins would get the ttyrec encrypted file, +decrypt the second encryption layer (the first for decryption), and handle the now only auditor-protected file to the auditors. +All public keys must be in the local root keyring (gpg --list-keys). +Don't forget to trust those keys "ultimately" in root's keyring, too (gpg --edit-key ID) + +encrypt_and_move_to_directory +***************************** + +:Type: ``string, a valid directory name`` + +:Default: ``"/home/.encrypt"`` + +After encryption (and compression), move ttyrec, user sqlite and user log files to subdirs of this directory. +It'll be created if it doesn't exist yet. +You may want this directory to be the mount point of a remote filer, if you wish. +If you change this, it's probably a good idea to ensure that the path is excluded from the +master/slave synchronization, in ``/etc/bastion/osh-sync-watcher.rsyncfilter``. +This is already the case for the default value. + +encrypt_and_move_ttyrec_delay_days +********************************** + +:Type: ``int > 0, or -1`` + +:Default: ``14`` + +Don't touch ttyrec files that have a modification time more recent than this amount of days. +The files won't be encrypted nor moved yet, and will still be readable by the ``selfPlaySession`` command. +You can set this to a (possibly) much higher value, the only limit is the amount of disk space you have. +If set to -1, the ttyrec files will never get encrypted or moved by this script. +The eligible files will be encrypted and moved to ``encrypt_and_move_to_directory``. +NOTE: The old name of this option is `encrypt_and_move_delay_days`. +If it is found in your configuration file and `encrypt_and_move_ttyrec_delay_days` is not, +then the value of `encrypt_and_move_delay_days` will be used instead of the default. + +encrypt_and_move_user_logs_delay_days +************************************* + +:Type: ``int >= 31, or -1`` + +:Default: ``31`` + +Don't touch user log files (``/home/*/*.log``) that have been modified more recently than this amount of days. +The bare minimum is 31 days, to ensure we're not moving a current-month file. +You can set this to a (possibly) much higher value, the only limit is the amount of disk space you have. +If set to -1, the user log files will never get encrypted or moved by this script. +The eligible files will be encrypted and moved to ``encrypt_and_move_to_directory``. + +encrypt_and_move_user_sqlites_delay_days +**************************************** + +:Type: ``int >= 31, or -1`` + +:Default: ``31`` + +Don't touch user sqlite files (``/home/*/*.sqlite``) that have been modified more recently than this amount of days. +The files won't be encrypted nor moved yet, and will still be usable by the ``selfListSessions`` command. +The bare minimum is 31 days, to ensure we're not moving a current-month file. +You can set this to a (possibly) much higher value, the only limit is the amount of disk space you have. +If set to -1, the user sqlite files will never get encrypted or moved by this script. +The eligible files will be encrypted and moved to ``encrypt_and_move_to_directory``. + +Push files to a remote destination +---------------------------------- + +rsync_destination +***************** + +:Type: ``string`` + +:Default: ``""`` + +:Example: ``"user@remotebackup.example.org:/remote/dir"`` + +The value of this option will be passed to ``rsync`` as the destination. +Note that the source of the rsync is already configured above, as the ``encrypt_and_move_to_directory``. +We only rsync the files that have already been encrypted and moved there. +If this option is empty, this will **disable** ``rsync``, meaning that the ttyrec files will be encrypted, +but not moved out of the server. In other words, the files will pile up in ``encrypt_and_move_to_directory``, +which can be pretty okay in you have enough disk space. + +rsync_rsh +********* + +:Type: ``string`` + +:Default: ``""`` + +:Example: ``"ssh -p 222 -i /root/.ssh/id_ed25519_backup"`` + +The value of this option will be passed to ``rsync``'s ``--rsh`` option. +This is useful to specify an SSH key or an alternate SSH port for example. +This option is ignored when ``rsync`` is disabled (i.e. when ``rsync_destination`` is empty). + +rsync_delay_before_remove_days +****************************** + +:Type: ``int >= 0, or -1`` + +:Default: ``0`` + +After encryption/compression, and successful rsync of ``encrypt_and_move_to_directory`` to remote, +wait for this amount of days before removing the encrypted/compressed files locally. +Specify 0 to remove the files as soon as they're transferred. +This option is ignored when ``rsync`` is disabled (i.e. when ``rsync_destination`` is empty). +Note that if rsync is enabled (see ``rsync_destination`` above), we'll always sync the files present in +``encrypt_and_move_to_directory`` as soon as we can, to ensure limitation of logs data loss in case of +catastrophic failure of the server. The ``rsync_delay_before_remove_days`` option configures the number +of days after we remove the files locally, but note that these have already been transferred remotely +as soon as they were present in ``encrypt_and_move_to_directory``. +To rsync the files remotely but never delete them locally, set this to -1. + diff --git a/_sources/administration/configuration/osh-http-proxy_conf.rst.txt b/_sources/administration/configuration/osh-http-proxy_conf.rst.txt new file mode 100644 index 0000000..6dbac53 --- /dev/null +++ b/_sources/administration/configuration/osh-http-proxy_conf.rst.txt @@ -0,0 +1,178 @@ +=================== +osh-http-proxy.conf +=================== + + .. note:: + + This module is optional, and disabled by default. + To know more about the HTTP Proxy feature of The Bastion, + please check the :doc:`/using/http_proxy` section + +Option List +=========== + +HTTP Proxy configuration options +-------------------------------- + +These options modify the behavior of the HTTP Proxy, an optional module of The Bastion + +- `enabled`_ +- `port`_ +- `ssl_certificate`_ +- `ssl_key`_ +- `ciphers`_ +- `insecure`_ +- `min_servers`_ +- `max_servers`_ +- `min_spare_servers`_ +- `max_spare_servers`_ +- `timeout`_ +- `log_request_response`_ +- `log_request_response_max_size`_ + +Option Reference +================ + +HTTP Proxy configuration +------------------------ + +enabled +******* + +:Type: ``bool`` + +:Default: ``false`` + +Whether the HTTP proxy daemon daemon is enabled or not. If it's not enabled, it'll exit when started. +Of course, if you want to enable this daemon, you should **also** configure your init system to start it +for you. Both sysV-style scripts and systemd unit files are provided. +For systemd, using `systemctl enable osh-http-proxy.service` should be enough. +For sysV-style inits, it depends on the scripts provided for your distro, +but usually `update-rc.d osh-http-proxy defaults` then `update-rc.d osh-http-proxy enable` should +do the trick. + +port +**** + +:Type: ``int, 1 to 65535`` + +:Default: ``8443`` + +The port to listen to. You can use ports < 1024, in which case privileges will be dropped after binding, +but please ensure your systemd unit file starts the daemon as root in that case. + +ssl_certificate +*************** + +:Type: ``string`` + +:Default: ``/etc/ssl/certs/ssl-cert-snakeoil.pem`` + +The file that contains the server SSL certificate in PEM format. +For tests, install the ``ssl-cert`` package and point this configuration item +to the snakeoil certs (which is the default). + +ssl_key +******* + +:Type: ``string`` + +:Default: ``/etc/ssl/private/ssl-cert-snakeoil.key`` + +The file that contains the server SSL key in PEM format. +For tests, install the ``ssl-cert`` package and point this configuration item +to the snakeoil certs (which is the default). + +ciphers +******* + +:Type: ``string`` + +:Default: ``""`` + +:Example: ``"ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256"`` + +The ordered list the TLS server ciphers, in ``openssl`` classic format. Use ``openssl ciphers`` +to see what your system supports, an empty list leaves the choice to your openssl libraries default +values (system-dependent) + +insecure +******** + +:Type: ``bool`` + +:Default: ``false`` + +Whether to ignore SSL certificate verification for the connection between the bastion and the devices + +min_servers +*********** + +:Type: ``int, 1 to 512`` + +:Default: ``8`` + +Number of child processes to start at launch + +max_servers +*********** + +:Type: ``int, 1 to 512`` + +:Default: ``32`` + +Hard maximum number of child processes that can be active at any given time no matter what + +min_spare_servers +***************** + +:Type: ``int, 1 to 512`` + +:Default: ``8`` + +The daemon will ensure that there is at least this number of children idle & ready to accept +new connections (as long as max_servers is not reached) + +max_spare_servers +***************** + +:Type: ``int, 1 to 512`` + +:Default: ``16`` + +The daemon will kill *idle* children to keep their number below this maximum when traffic is low + +timeout +******* + +:Type: ``int, 1 to 3600`` + +:Default: ``120`` + +Timeout delay (in seconds) for the connection between the bastion and the devices + +log_request_response +******************** + +:Type: ``bool`` + +:Default: ``true`` + +When enabled, the complete response of the device to the request we forwarded will be logged, +otherwise we'll only log the response headers + +log_request_response_max_size +***************************** + +:Type: ``int, 0 to 2^30 (1 GiB)`` + +:Default: ``65536`` + +This option only applies when `log_request_response` is true (see above). +When set to zero, the complete response will be logged in the account's home log directory, +including the body, regardless of its size. If set to a positive integer, +the query response will only be partially logged, with full status and headers but the body only up +to the specified size. This is a way to avoid turning off request response logging completely on +very busy bastions, by ensuring logs growth don't get out of hand, as some responses to queries can +take megabytes, with possibly limited added value to traceability. + diff --git a/_sources/administration/configuration/osh-lingering-sessions-reaper_conf.rst.txt b/_sources/administration/configuration/osh-lingering-sessions-reaper_conf.rst.txt new file mode 100644 index 0000000..e24343b --- /dev/null +++ b/_sources/administration/configuration/osh-lingering-sessions-reaper_conf.rst.txt @@ -0,0 +1,81 @@ +================================== +osh-lingering-sessions-reaper.conf +================================== + + .. note:: + + This script is called by cron and is responsible for terminating + lingering sessions that no longer have any tty attached nor parent PID, + and have been running for some time. + +Option List +=========== + +Logging & activation options +---------------------------- + +Script logging configuration and script activation + +- `LOGFILE`_ +- `LOG_FACILITY`_ +- `ENABLED`_ + +Main options +------------ + +These options govern the behavior of the script + +- `MAX_AGE`_ + +Option Reference +================ + +Logging & activation +-------------------- + +LOGFILE +******* + +:Type: ``string, path to a file`` + +:Default: ``""`` + +File where the logs will be written to (don't forget to configure ``logrotate``!). +Note that using this configuration option, the script will directly write to the file, without using syslog. +If empty, won't log directly to any file. + +LOG_FACILITY +************ + +:Type: ``string`` + +:Default: ``"local6"`` + +The syslog facility to use for logging the script output. +If set to the empty string, we'll not log through syslog at all. +If this configuration option is missing from your config file altogether, +the default value will be used (local6), which means that we'll log to syslog. + +ENABLED +******* + +:Type: ``0 or 1`` + +:Default: ``1`` + +If set to 1, the script is enabled and will run when started by crond. + +Main +---- + +MAX_AGE +******* + +:Type: ``int >= 0`` + +:Default: ``86400`` + +The minimum number of seconds a session must have been opened before +being considered as possibly a lingering orphan session. +Still alive sessions, even older than MAX_AGE seconds, will be kept. + diff --git a/_sources/administration/configuration/osh-orphaned-homedir_conf.rst.txt b/_sources/administration/configuration/osh-orphaned-homedir_conf.rst.txt new file mode 100644 index 0000000..de0bccd --- /dev/null +++ b/_sources/administration/configuration/osh-orphaned-homedir_conf.rst.txt @@ -0,0 +1,62 @@ +========================= +osh-orphaned-homedir.conf +========================= + + .. note:: + + This script is called by cron and is responsible for clearing up + orphaned home directories on secondary bastions. + Indeed, once the user has been deleted, a few files may remain, + such as logs, so this script handles the proper archiving + of these sparse files, before removing the orphaned home directory. + +Option List +=========== + +Logging & activation options +---------------------------- + +Script logging configuration and script activation + +- `LOGFILE`_ +- `LOG_FACILITY`_ +- `ENABLED`_ + +Option Reference +================ + +Logging & activation +-------------------- + +LOGFILE +******* + +:Type: ``string, path to a file`` + +:Default: ``""`` + +File where the logs will be written to (don't forget to configure ``logrotate``!). +Note that using this configuration option, the script will directly write to the file, without using syslog. +If empty, won't log directly to any file. + +LOG_FACILITY +************ + +:Type: ``string`` + +:Default: ``"local6"`` + +The syslog facility to use for logging the script output. +If set to the empty string, we'll not log through syslog at all. +If this configuration option is missing from your config file altogether, +the default value will be used (local6), which means that we'll log to syslog. + +ENABLED +******* + +:Type: ``0 or 1`` + +:Default: ``1`` + +If set to 1, the script is enabled and will run when started by crond. + diff --git a/_sources/administration/configuration/osh-piv-grace-reaper_conf.rst.txt b/_sources/administration/configuration/osh-piv-grace-reaper_conf.rst.txt new file mode 100644 index 0000000..ca678c7 --- /dev/null +++ b/_sources/administration/configuration/osh-piv-grace-reaper_conf.rst.txt @@ -0,0 +1,48 @@ +========================= +osh-piv-grace-reaper.conf +========================= + + .. note:: + + This script is called by cron and is responsible for removing temporary + grace periods on PIV policies, once they expire. If you don't use PIV keys, + this script won't do anything (see :doc:`/using/piv`). + +Option List +=========== + +Logging & activation options +---------------------------- + +Script logging configuration and script activation + +- `syslog_facility`_ +- `enabled`_ + +Option Reference +================ + +Logging & activation +-------------------- + +syslog_facility +*************** + +:Type: ``string`` + +:Default: ``local6`` + +The syslog facility to use for logging the script output. +If set to the empty string, we'll not log through syslog at all. +If this configuration option is missing from your config file altogether, +the default value will be used (local6), which means that we'll log to syslog. + +enabled +******* + +:Type: ``bool`` + +:Default: ``true`` + +If not set to `true` (or a true value), the script will not run. + diff --git a/_sources/administration/configuration/osh-remove-empty-folders_conf.rst.txt b/_sources/administration/configuration/osh-remove-empty-folders_conf.rst.txt new file mode 100644 index 0000000..54f63bb --- /dev/null +++ b/_sources/administration/configuration/osh-remove-empty-folders_conf.rst.txt @@ -0,0 +1,84 @@ +============================= +osh-remove-empty-folders.conf +============================= + + .. note:: + + This script is called by cron and is responsible for getting rid of empty + folders in the ``ttyrec/`` directory of users homes, which may contain a + high amount of empty folders for busy users connecting to a lot of + different servers, as we create one folder per destination IP. + Of course, this script will only remove empty folders, never actual files. + +Option List +=========== + +Logging & activation options +---------------------------- + +Script logging configuration and script activation + +- `LOGFILE`_ +- `LOG_FACILITY`_ + +Behavior options +---------------- + +These options govern the behavior of the script + +- `ENABLED`_ +- `MTIME_DAYS`_ + +Option Reference +================ + +Logging & activation +-------------------- + +LOGFILE +******* + +:Type: ``string, path to a file`` + +:Default: ``""`` + +File where the logs will be written to (don't forget to configure ``logrotate``!). +Note that using this configuration option, the script will directly write to the file, without using syslog. +If empty, won't log directly to any file. + +LOG_FACILITY +************ + +:Type: ``string`` + +:Default: ``"local6"`` + +The syslog facility to use for logging the script output. +If set to the empty string, we'll not log through syslog at all. +If this configuration option is missing from your config file altogether, +the default value will be used (local6), which means that we'll log to syslog. + +Behavior +-------- + +ENABLED +******* + +:Type: ``0 or 1`` + +:Default: ``1`` + +If set to 1, the script is enabled and will attempt to garbage-collect empty directories located +in ``/home/*/ttyrec``. If set to anything else, the script is considered disabled and will not run. + +MTIME_DAYS +********** + +:Type: ``int, >= 0`` + +:Default: ``1`` + +The amount of days the empty folder must have been empty before considering a removal. You probably +don't need to change the default value, unless you want to ensure that a given folder has not been +used since some time before removing it (this has no impact as folders are re-created as needed). + diff --git a/_sources/administration/configuration/osh-sync-watcher_sh.rst.txt b/_sources/administration/configuration/osh-sync-watcher_sh.rst.txt new file mode 100644 index 0000000..c0cc7ff --- /dev/null +++ b/_sources/administration/configuration/osh-sync-watcher_sh.rst.txt @@ -0,0 +1,119 @@ +=================== +osh-sync-watcher.sh +=================== + + .. note:: + + This daemon is responsible for ensuring secondary bastions + are synced up to their primary at all times. + If you don't have such HA setup, you can ignore this config file. + For more information, refer to + :ref:`installation/advanced:clustering (high availability)`. + +Option List +=========== + +Logging options +--------------- + +These options configure the way the script logs its actions + +- `logdir`_ +- `syslog`_ + +Daemon setup options +-------------------- + +These options configure whether the synchronization daemon is enabled + +- `enabled`_ +- `timeout`_ + +Remote synchronization options +------------------------------ + +These options configure how the primary bastion should push its configuration to the secondaries + +- `rshcmd`_ +- `remoteuser`_ +- `remotehostlist`_ + +Option Reference +================ + +Logging +------- + +logdir +****** + +:Type: ``string`` + +:Default: ``""`` + +Directory where the logs will be written to. Note that using this configuration option, the script will directly write to a file, without using syslog. If empty, won't log directly to a file. + +syslog +****** + +:Type: ``string`` + +:Default: ``"local6"`` + +The syslog facility to use for logging the script output. If set to the empty string, we'll not log through syslog at all. If this configuration option is missing from your config file altogether, the default value will be used (local6), which means that we'll log to syslog. + +Daemon setup +------------ + +enabled +******* + +:Type: ``int`` + +:Default: ``0`` + +If set to anything else than ``1``, the daemon will refuse to start (e.g. you don't have secondary bastions). You can set this to ``1`` when you've configured and tested the primary/secondaries setup. + +timeout +******* + +:Type: ``int > 0`` + +:Default: ``120`` + +The maximum delay, in seconds, after which we'll forcefully synchronize our data to the secondaries, even if no change was detected. + +Remote synchronization +---------------------- + +rshcmd +****** + +:Type: ``string`` + +:Default: ``""`` + +:Example: ``"ssh -q -i /root/.ssh/id_master2slave -o StrictHostKeyChecking=accept-new"`` + +This value will be passed as the ``--rsh`` parameter of ``rsync`` (don't use ``-p`` to specify the port here, use the ``remotehostlist`` config below instead), this can be used to specify which SSH key to use, for example. NOTE THAT THIS OPTION IS MANDATORY (if you don't have anything to specify here, you can just say ``ssh``). If you followed the standard installation procedure, the "example" value specified below will work. + +remoteuser +********** + +:Type: ``string`` + +:Default: ``"bastionsync"`` + +The remote user to connect as, using ``ssh`` while rsyncing to secondaries. You probably don't need to change this. + +remotehostlist +************** + +:Type: ``space-separated list of strings, each string being either 'ip' or 'ip:port'`` + +:Default: ``""`` + +:Example: ``"192.0.2.17 192.0.2.12:2244"`` + +The list of the secondary bastions to push our data to. If this list is empty, the daemon won't do anything. + diff --git a/_sources/administration/logs.rst.txt b/_sources/administration/logs.rst.txt new file mode 100644 index 0000000..53fe5d2 --- /dev/null +++ b/_sources/administration/logs.rst.txt @@ -0,0 +1,599 @@ +==== +Logs +==== + +.. note:: + The Bastion comes with a lot of traceability features, you have to ensure that you've done your configuration + correctly so that those logs are kept in a safe place when you need them. It is warmly advised to enable at least + the syslog option, and push your logs to a remote syslog server. + +.. contents:: + :depth: 5 + + +Message types +============= + +The Bastion has several configurable ways of logging events, but before detailing those, +let's see the different message types that can be logged. +The Bastion currently has 12 different message types, listed below: + +- :ref:`log_open` +- :ref:`log_close` +- :ref:`log_warn` +- :ref:`log_warninfo` +- :ref:`log_codewarn` +- :ref:`log_acl` +- :ref:`log_membership` +- :ref:`log_security` +- :ref:`log_group` +- :ref:`log_account` + +First, let's list the fields that are common to all the message types: + +uniqid + This is the unique connection ID, you can find all the logs relevant to the same connection + by filtering on the ``uniqid``. This ID is also, by default, part of the filename given to the ``ttyrec`` files, + for easier correlation. The same ID is also used in the sqlite logs, if you enabled those. In some rare cases, + the value can be "-", for example if a satellite script has something to log, + not linked to an actual connection or session. + +version + This indicates the version of The Bastion software that is writing the log + +pid, ppid + This is the system PID (resp. system parent PID) of the process writing the log, + for easier correlation with system audit logs if you have them + +sysuser + This is the system user under which the process writing the log is currently running on, + can be useful to detect abnormalities + +sudo_user + When the value is present, it contains the system user name that has launched the ``sudo`` command the code is + currently running under (this will be the case if a so-called "bastion helper" is pushing a log, for example). + However this field will often have an empty value, it means that the code that is writing the log + is not running under ``sudo`` + +uid, gid + This is the system user ID aka UID (resp. group ID aka GID) under which + the process writing the log is currently running + +account + This is the name of the bastion account that launched the command that produced the log + +The other fields depend on the message type, as detailed in the next sections. + +.. _log_open: + +open +**** + +This log is produced when a user established a session with the bastion. + +Example:: + + Dec 28 11:12:26 myhostname bastion: open uniqid="e9e4baf6873b" version="3.01.03" pid="18721" ppid="18720" + sysuser="gthreepw" sudo_user="" uid="99998" gid="99998" account="gthreepw" cmdtype="ssh" allowed="true" + ip_from="172.17.0.1" port_from="39696" host_from="172.17.0.1" ip_bastion="172.17.0.2" port_bastion="22" + host_bastion="myhostname.example.org" user="foo" ip_to="172.17.0.123" port_to="22" host_to="srv123.example.org" + plugin="" globalsql="ok" accountsql="ok" comment="" params="ttyrec -f + /home/gthreepw/ttyrec/172.17.0.123/2020-12-28.11-12-26.074894.e9e4baf6873b.gthreepw.foo.172.17.0.123.22.ttyrec -F + /home/gthreepw/ttyrec/172.17.0.123/%Y--%d.%H-%M-%S.#usec#.e9e4baf6873b.gthreepw.foo.172.17.0.123.22.ttyrec -- + /usr/bin/ssh 172.17.0.123 -l foo -p 22 -i /home/gthreepw/.ssh/id_rsa4096_private.1594384739 -i + /home/keykeeper/keyagroup/id_ed25519_agroup.1607524914 -o PreferredAuthentications=publickey" + +Fields: + +cmdtype + Indicates which category of command has been requested by the user: + + - ssh: the user is trying to establish an SSH egress connection to a remote server + - telnet: the user is trying to establish a telnet egress connection to a remote server + - abort: the action requested by the user has been aborted early, possibly because of permission issues + or impossibility to understand the request, more information is available in the **bastion_comment** field + - osh: the user is trying to execute a bastion plugin with the ``--osh`` command + - interactive: the user just entered interactive mode. Note that all the commands launched through + the interactive mode will still have their own log. + - sshas: an administrator is currently establishing a connection on behalf of another user. + This connection will also have its own log. + - proxyhttp_daemon: the HTTPS proxy daemon received a request + - proxyhttp_worker: the HTTPS proxy worker specifically spawned for the user by the daemon is handling the request + +allowed + Indicates whether the requested action was allowed or not by the bastion, after executing the authorization phase. + Will be either "true" or "false". + +ip_from, port_from, host_from + These are the IP and source port as seen by the bastion, from which the ingress connection originates. + If the bastion can resolve the reverse of the IP to a hostname, it'll be indicated in host_from, + otherwise the IP will be repeated there. + +ip_bastion, port_bastion, host_bastion + These are the IP and port of the bastion to which the ingress connection terminates. + If your bastion has several IPs and/or interfaces, this can be useful. + If the bastion can resolve the reverse of the IP to a hostname, it'll be indicated in host_bastion, + otherwise the IP will be repeated there. + +ip_to, port_to, host_to + These are the IP and destination port to which the bastion will connect on the egress side, + on behalf of the requesting user. If the bastion can resolve the reverse of the IP to a hostname, + it'll be indicated in host_to, otherwise the IP will be repeated there. + +plugin + When ``cmdtype`` is ``osh``, the name of the command (or *plugin*) will appear in this field. + Otherwise it'll be blank. + +accountsql + This field will contain either: + + - ok: when :ref:`enableAccountSqlLog` is enabled, and we successfully inserted a new row for the log + - no: when :ref:`enableAccountSqlLog` is disabled + - error: when we couldn't insert a new row, **error** followed by a detailed error message, + for example "error SQL error [global] err 8 while doing [inserting data (execute)]: + attempt to write a readonly database". + +globalsql + This field can contain the same values than **accountsql** above, + but for ``enableGlobalSqlLog`` instead of ``enableAccountSqlLog`` + +comment + Some more information about the current event, depending on the ``cmdtype`` value. + +params + This is the fully expanded command line that will be launched under the currently running user rights, + to establish the egress connection, if applicable. + +.. _log_close: + +close +***** + +This log is produced when a user terminates a currently running session with The Bastion. +It is always matched (through the ``uniqid``) to another log with the ``open`` message type. + +Example:: + + Dec 28 11:12:26 myhostname bastion: open uniqid="e9e4baf6873b" version="3.01.03" pid="18721" ppid="18720" + sysuser="gthreepw" sudo_user="" uid="99998" gid="99998" account="gthreepw" cmdtype="ssh" allowed="true" + ip_from="172.17.0.1" port_from="39696" host_from="172.17.0.1" ip_bastion="172.17.0.2" port_bastion="22" + host_bastion="myhostname.example.org" user="foo" ip_to="172.17.0.123" port_to="22" + host_to="srv123.example.org" plugin="" globalsql="ok" accountsql="ok" comment="" params="ttyrec -f + /home/gthreepw/ttyrec/172.17.0.123/2020-12-28.11-12-26.074894.e9e4baf6873b.gthreepw.foo.172.17.0.123.22.ttyrec -F + /home/gthreepw/ttyrec/172.17.0.123/%Y--%d.%H-%M-%S.#usec#.e9e4baf6873b.gthreepw.foo.172.17.0.123.22.ttyrec -- + /usr/bin/ssh 172.17.0.123 -l foo -p 22 -i /home/gthreepw/.ssh/id_rsa4096_private.1594384739 -i + /home/keykeeper/keyagroup/id_ed25519_agroup.1607524914 -o PreferredAuthentications=publickey" sysret="0" + signal="" comment_close="hostkey_changed passauth_disabled" duration="43.692" + +All the fields from the corresponding ``open`` log are repeated in this log line, in addition to the following fields: + +sysret + Return code of the launched system command (that established the egress connection) + or the plugin (if an ``--osh`` command was passed). + If we don't have a return code, for example because we were interrupted by a signal, the value will be empty. + +signal + Name of the UNIX signal that terminated the command, if any. For example "HUP" or "SEGV". + If we got no signal, the value will be empty. + +comment_close + A space-separated list of messages giving some hints gathered at the end of a session. + For example `hostkey_changed passauth_disabled` means that we detected that our egress ssh client + emitted a warning telling us that the remote keys changed, and also that password authentication has been disabled. + +duration + Amount of seconds (with a millisecond precision) between the session open and the session close. + +.. _log_warn: + +warn, die +********* + +These logs are produced when Perl emits a warning (using the ``warn()`` call), +or respectively when Perl halts abruptly due to a ``die()`` call. +This should not happen during nominal use. You might want to keep a look on those messages if they're produced. + +Example:: + + Dec 28 11:12:26 myhostname bastion: warn uniqid="a46e51b5dce4" version="3.01.02" pid="3308212" ppid="3308206" + sysuser="lechuck" sudo_user="" uid="99994" gid="99994" msg="Cannot find termcap: TERM not set at + /usr/share/perl/5.28/Term/ReadLine.pm line 379. " program="/opt/bastion/bin/shell/osh.pl" cmdline="-c^-i ssh + root@172.17.0.222 id" trace=" at /opt/bastion/bin/shell/../../lib/perl/OVH/Bastion.pm + line 41. OVH::Bastion::__ANON__(\"Cannot find termcap: TERM not set at /usr/share/perl/5.28/Ter\"...) + called at /usr/share/perl/5.28/Term/ReadLine.pm line + 391 Term::ReadLine::TermCap::ornaments(Term::ReadLine::Stub=ARRAY(0x5575da36b690), 1) called at + /opt/bastion/lib/perl/OVH/Bastion/interactive.inc line 77 OVH::Bastion::interactive(\"realOptions\", \"-i ssh + root\\@172.17.0.222 id\"..., \"timeoutHandler\", CODE(0x5575da15aa78), \"self\", \"lechuck\") + called at /opt/bastion/bin/shell/osh.pl line 485 " + +Fields: + +msg + This is the message used as a parameter to the ``warn()`` or ``die()`` call + +program + Contains the name of the currently running program (first parameter of ``execve()``) + +cmdline + Contains the full command line passed to the currently running program (remaining parameters of ``execve()``). + The command-line fields are separated by ``^``'s. + +trace + The call trace leading to this ``warn()`` or ``die()`` + +.. _log_warninfo: + +warn-info, die-info +******************* + +These logs are produced when some known portion of code (including libraries) called ``warn()`` or ``die()`` +but in a known case that can happen during nominal use. +Don't use these logs to directly trigger an alert, but you can keep an eye on those, as e.g. an unusually +high number of occurences in a short time may be a weak signal that somebody or something is misbehaving. + +The fields are the same than the ones specified above for **warn** and **die**. + +.. _log_codeinfo: + +code-info +********* + +These logs are produced when some portion of the code encounters an minor issue that is worth logging, +to e.g. help debugging an issue or understanding what happened in a specific use-case, +for example if a user-session ended abruptly. +These logs are not the result of an error on the bastion configuration and don't mandate immediate admin attention. + +Example:: + + Dec 25 14:56:11 myhostname bastion: code-info uniqid="98d2f32b1a2d" version="3.07.00" pid="3708843" + ppid="3708842" sysuser="lechuck" sudo_user="" uid="8423" gid="8423" msg="execute(): + error while syswriting(Broken pipe) on stderr, aborting this cycle" + +Fields: + +msg + A human-readable text describing the error + +.. _log_codewarn: + +code-warning +************ + +These logs are produced when some portion of the code encounters an unexpected issue or abnormality +that is worth logging. They'll usually not be emitted due to a bad user interaction, but rather if the bastion +is misconfigured, or for anything that might need some attention or fixing from the admins. + +Example:: + + Dec 28 11:12:26 myhostname bastion: code-warning uniqid="ffee33abd1ba" version="3.01.03" pid="3709643" + ppid="3709642" sysuser="lechuck" sudo_user="" uid="8423" gid="8423" msg="Configuration error + for plugin selfGenerateEgressKey on the 'disabled' key: expected a boolean, casted 'no' into false" + +Fields: + +msg + A human-readable text describing the error + +.. _log_acl: + +acl +*** + +This log is produced when an access control list is modified, +either personal accesses of an account, or a group servers list. + +Example:: + + Dec 28 11:12:26 myhostname bastion: acl uniqid="f25fe71c6635" version="3.01.02" pid="3116604" + ppid="3116603" sysuser="keysomegroup" sudo_user="lechuck" uid="10006" gid="10057" action="add" + type="group" group="somegroup" account="" user="root" ip="172.16.2.2" port="22" ttl="" force_key="" comment="" + +Fields: + +action + Will be either *add* if an access is added, or *del* if an access is removed + +type + Will be either *group* if we're modifying a group server list, in which case the *group* field will be filled, + or *account* if we're modifying personal accesses of an account, in which case the *account* field will be filled + +group + If **type** is *group*, indicates which group servers list has been modified + +account + If **type** is *account*, indicates which account personal accesses have been modified + +user + The remote user part of the access we're adding/removing + +ip + The IP or IP block of the access we're adding/removing + +port + The port of the access we're adding/removing + +ttl + If set, represents the TTL after which the access will automatically be removed + +force_key + If set, this contains the fingerprint of the key that'll be used for this access + +comment + Any comment set by the user adding/removing the access + +.. _log_membership: + +membership +********** + +This log is produced when one of a group's role list is modified: +either an owner, member, guest, aclkeeper or gatekeeper. + +Example:: + + Dec 28 11:12:26 myhostname bastion: membership uniqid="a00993ec6767" version="3.01.02" + pid="1072528" ppid="1072497" sysuser="lechuck" sudo_user="" uid="2070" gid="2070" action="add" + type="member" group="monkeys" account="stan" self="lechuck" user="" host="" port="" ttl="" + +Fields: + +action + Either *add* when an account is added to a group role list, or *del* when an account is removed + +type + Type of the role list we're modifying, either *member*, *aclkeeper*, *gatekeeper*, *guest* or *owner* + +group + Group whose one of the role list is being modified + +account + Account being added/removed to/from the group role list + +self + Account performing the change + +user + When **type** is *guest*, the remote user part of the access we're adding/removing + +host + When **type** is *guest*, the IP or IP block part of the access we're adding/removing + +port + When **type** is *guest*, the port of the access we're adding/removing + +ttl + When **type** is *guest* and **action** is *add*, if a TTL has been specified for the access, it appears here + +.. _log_security: + +security +******** + +This log is produced when an important security event has occurred, such as when an admin impersonates another user, +or when a super owner uses his implicit global ownership to modify a group. You might want to watch those closely. + +Example:: + + Dec 28 11:12:26 myhostname bastion: security uniqid="601a17b5e5ba" version="3.01.03" pid="20519" + ppid="20518" sysuser="lechuck" sudo_user="" uid="2604" gid="2604" type="admin-ssh-as" account="lechuck" + sudo-as="gthreepw" plugin="ssh" params="--user root --host supersecretserver.example.org --port 22" + +Fields: + +type + Type of the security event that occurred. Can be: + + - admin-ssh-as: an admin impersonated another user to establish an egress connection + - admin-sudo: an admin impersonated another user and launched an osh plugin on their behalf + - superowner-override: a super owner used his implicit ownership on all groups to modify a group + +account + Account that emitted the security event + +sudo-as + When **type** is *admin-ssh-as* or *admin-sudo*, name of the account that was impersonated + +plugin + Name of the osh plugin that was launched + +params + Parameters passed to the plugin, or command line used to establish the egress connection + +.. _log_group: + +group +***** + +This log is produced when a group is created or deleted. +Note that membership modifications are referenced with the **membership** type instead, see above. + +Example:: + + Dec 28 11:12:26 myhostname bastion: group uniqid="56f321fb3e58" version="3.01.03" pid="1325901" + ppid="1325900" sysuser="root" sudo_user="lechuck" uid="0" gid="0" action="create" group="themonkeys" + owner="stan" egress_ssh_key_algorithm="ed25519" egress_ssh_key_size="256" egress_ssh_key_encrypted="false" + +Fields: + +action + Either *create* or *delete*, indicating whether the group has just been created or deleted + +group + The group name being created or deleted + +owner + When **action** is *create*, the name of the owner of the new group we're creating + +egress_ssh_key_algorithm, egress_ssh_key_size + When **action** is *create*, the algorithm (and size) used to generate the first pair of SSH keys, + can be empty if ``--no-key`` was specified + +egress_ssh_key_encrypted + When **action** is *create*, if a key was generated, + will be *true* if ``--encrypted`` has been used, *false* otherwise + +.. _log_account: + +account +******* + +This log is produced when an account is created or deleted. + +Example:: + + Dec 21 14:30:26 myhostname bastion: account uniqid="ee4c91000b75" version="3.01.02" pid="537253" ppid="537252" + sysuser="root" sudo_user="lechuck" uid="0" gid="0" action="create" account="stan" account_uid="8431" + public_key="ssh-rsa AAAAB[...]" always_active="false" uid_auto="false" osh_only="false" immutable_key="false" + comment="CREATED_BY=lechuck BASTION_VERSION=3.01.02 CREATION_TIME=Mon Dec 21 14:30:26 2020 + CREATION_TIMESTAMP=1608561026 COMMENT=requested_by_the_sword_master_of_melee_island_see_ticket_no_1337" + +Fields: + +action + Either *create* or *delete*, indicating whether the account has just been created or deleted + +account + The account name being created or deleted + +account_uid + When **action** is *create*, the UID associated corresponding to the account we're creating + +public_key + When **action** is *create*, the public key we've generated for the new account + +always_active, uid_auto, osh_only, immutable_key + When **action** is *create*, *true* if the corresponding option was specified (``--always-active``, + ``--uid-auto``, ``--osh-only`` or ``--immutable-key``), *false* otherwise + +comment + When **action** is *create*, the comment specified at creation if any, with some metadata that'll be stored in + the account properties (*created_by*, *bastion_version*, *creation_time*, *creation_timestamp*) + +tty_group + When **action** is *delete*, the name of the tty group specific to this account that was deleted at the same time + +.. _syslog: + +Syslog +====== + +Files location +************** + +If you use ``syslog-ng`` and installed the provided templates (which is the default if you used +the ``--new-install`` option to the install script), you'll have 4 files in your system log directory: + +/var/log/bastion/bastion.log + This is where all the bastion usage logs will be written. All the above message types can be found in this file. + +/var/log/bastion/bastion-die.log + This is where Perl crashes will be logged, with the message type ``die``. + On a production bastion, this file should normally be empty. + +/var/log/bastion/bastion-warn.log + This is where Perl warnings will be logged, with the message type ``warning``. + On a production bastion, this file should mostly be empty. + +/var/log/bastion/bastion-scripts.log + This is where all the satellite scripts (mostly found in the ``bin/cron/`` directory) will log their output. + +Log format +********** + +A syslog message will always match the following generic format:: + + SYSLOG_TIME SYSLOG_HOST bastion: MSGTYPE field1="value1" field2="second value" ... + +Where SYSLOG_TIME is the usual datetime field added by your local syslog daemon, +and SYSLOG_HOST the hostname of the local machine. +The MSGTYPE indicates the message type of the log line (the list of types is further below). +Then, a possibly long list of fields with quoted values, depending on the MSGTYPE. + +An example follows:: + + Dec 28 11:14:23 myhostname bastion: code-warning uniqid="e192fce7553a" version="3.01.03" + pid="18803" ppid="18802" sysuser="gthreepw" sudo_user="" uid="99998" gid="99998" + msg="Configuration error: specified adminAccounts 'joe' is not a valid account, ignoring" + +In that case, the MSGTYPE is ``code-warning``, and we have a few field/value couples with some metadata of interest, +followed by a human-readable message, indicated by the ``msg`` field. + +Only satellite scripts will miss the field/value construction, which will just be replaced by a plain text message. +These logs are stored in :file:`/var/log/bastion/bastion-scripts.log` by default. + +Access logs +=========== + +If you don't or can't use :ref:`syslog`, the bastion can create and use access log files on its own, +without relying on a syslog daemon. Note that you can enable both syslog and these access logs, if you want. + +These access logs will only contain :ref:`log_open` and :ref:`log_close` log types, which can be seen as "access logs". +All the other log types, such as :ref:`log_warn`, :ref:`log_membership`, etc. are only logged through syslog. + +These logs are enabled through the :ref:`enableGlobalAccessLog` and :ref:`enableAccountAccessLog` options. + +enableGlobalAccessLog + When enabled, a single log file will be used, located in :file:`/home/logkeeper/global-log-YYYYMM.log`. + There will be one file per month. Note that it can grow quite large if you have a busy bastion. + +enableAccountAccessLog + When enabled, one log file per account will be used, located in :file:`/home/USER/USER-log-YYYYMM.log`. + There will be one file per month. + +If both options are enabled, it means that every access log will be logged twice, to two different locations. +If you also enabled syslog, it's even three times! + +SQLite logs +=========== + +If you want to store access logs into local sqlite databases, you can enable either :ref:`enableGlobalSqlLog`, +:ref:`enableAccountSqlLog`, or both. + +enableGlobalSqlLog + When enabled, a global sqlite database will be created in :file:`/home/logkeeper/global-log-YYYYMM.sqlite`. + It'll contain one row per access (created at the same time the :ref:`log_open` log is emitted). + The following columns exist: id, timestamp, account, cmdtype, allowed, ipfrom, ipto, portto, user, plugin, uniqid. + Refer to the :ref:`log_open` log description to get the meaning of each column. + +enableAccountSqlLog + When enabled, an sqlite database per account will be created in :file:`/home/USER/USER-log-YYYYMM.sqlite`. + It'll contain one row per access (created at the same time the :ref:`log_open` log is emitted), + and the same row will be updated by the :ref:`log_close` event when it is emitted. The following columns exist: + id, timestamp, timestampusec, account, cmdtype, allowed, hostfrom, ipfrom, bastionip, bastionport, hostto, + ipto, portto, user, plugin, ttyrecfilee, params, timestampend, timestampendusec, returnvalue, comment, uniqid. + Refer to the :ref:`log_open` log and :ref:`log_close` log descriptions to get the meaning of each column. + Note that the :ref:`enableAccountSqlLog` option is required if you want the :doc:`/plugins/open/selfListSessions` + and :doc:`/plugins/open/selfPlaySession` plugins to work, as they use this database. + +Note that enabling these on a very busy bastion (several new connections per second) can create lock contention, +especially on the global log: ensure you have a fast storage. In any case, if a connection can't get the lock after +a few seconds, it'll proceed anyway, and skip writing the sql log. In that case, if you enabled syslog or +local access logs, the **globalsql** and/or the **accountsql** field will contain the error detail. + +Terminal recordings (*ttyrec*) +============================== + +Every egress connection is started under ``ttyrec``, which means that everything appearing on the console is recorded. +If a password is asked by some program, for example, and typing the password prints '*' or doesn't print +anything at all, this won't be recorded. This is by design. In other words, the keystrokes are not recorded, +except if they produce something on the screen. + +The ttyrec files location is always :file:`/home/USER/ttyrec/REMOTEIP/file.ttyrec`, where the actual `file.ttyrec` +name can be configured by the :ref:`ttyrecFilenameFormat` option. +By default, it'll contain the date, time, account, remote ip, port and user used to start the egress connection, +as well as the uniqid, for easier correlation between all the logs produced by the same connection. +Note that for long connections, or connections producing a lot of output, ttyrec files will be transparently rotated, +without interrupting the connection. +This is to avoid ending up with ttyrec files of several gigabytes that would still be opened, written to, +hence impossible to compress, encrypt, and push to an escrow filer. +The uniqid will be the same for all the ttyrec files corresponding to the same connection. + +To play ttyrec files, you can either use :doc:`/plugins/open/selfPlaySession` for yourself, or, +for admins having local access to the bastion machine, the ``ttyplay`` program can be used. +Another software, perhaps more powerful than ttyplay, can also be used: +`IPBT `_ (`wiki `_), +aka "It's PlayBack Time", by the PuTTY author. +It can do more advanced things such as look for words appearing on any frame recorded in the ttyrec file, +play files using a logarithmic speed, or display an OSD with the exact time output you're seeing has appeared. +As ttyrec is a well-known format that has been around for a while, +there are a bunch of other programs you can use to read or convert these files. diff --git a/_sources/administration/mfa.rst.txt b/_sources/administration/mfa.rst.txt new file mode 100644 index 0000000..951e30a --- /dev/null +++ b/_sources/administration/mfa.rst.txt @@ -0,0 +1,441 @@ +=========================== +Multi-Factor Authentication +=========================== + +.. contents:: + +Introduction +============ + +Flavors +******* + +The Bastion supports two flavors of Multi-Factor Authentication (MFA, sometimes called 2FA): + +- `Immediate MFA`, mandatory on a per-account basis during the SSH authentication phase on the ingress side, + done by the system even before executing the bastion code, regardless of which actions (plugin calls, + remote connection, ...) are to be done by the account currently being authenticated + +- `JIT MFA`, done after the authentication phase, by the bastion code, conditionally (*just-in-time*), when + an action that is about to be done requires it by (configurable) policy + +Each of these methods and their differences are detailed below, so you can choose the one that fits your environment. + +Supported additional factors +**************************** + +The first factor is always the SSH publickey. Two additional factors are supported: + +- `password`, in which case a password is attached to the account. This password's policy is configurable through + :ref:`administration/configuration/bastion_conf:mfapasswordmindays`, + :ref:`administration/configuration/bastion_conf:mfapasswordmaxdays`, + :ref:`administration/configuration/bastion_conf:mfapasswordwarndays`, + :ref:`administration/configuration/bastion_conf:mfapasswordinactivedays`. + +- `TOTP`, aka "Time-based One-Time Password", which requires a smartphone app and generates a new pin-code every + 60 seconds. + +Immediate MFA +============= + +This method implements MFA directly using PAM during the initial SSH authentication phase, on the ingress +side, e.g. when accounts are connecting to the bastion. This entirely resides on SSH/PAM and doesn't even depend +on The Bastion code (appart from the setup side of the additional factor for each account). + +.. note:: + + Use this method if you want to enable MFA for some or all accounts unconditionally, regardless of which action + they're about to conduct on The Bastion (i.e. use an ``--osh`` command, or attempt to connect somewhere, + or just display the help). If you want to enable MFA only for some precise ``--osh`` commands or some remote hosts, + you'll want to use :ref:`jit_mfa` instead. + +This method requires proper configuration of both the SSH server, and PAM. The included templates of +:file:`/etc/ssh/sshd_config` and :file:`/etc/pam.d/ssh` files do support it out of the box. + +Detailed explanation of the SSH server and PAM configuration +************************************************************ + +This works by modifying the ``AuthenticationMethods`` in :file:`sshd_config` to add ``keyboard-interactive:pam``, +which instructs the SSH server to rely on PAM for part of the authentication phase. Then, the PAM file defines +several authentications methods, which include several factors that can be configured per-account. + +.. note:: + + You can skip this subsection if you're not interested in how this works exactly, but mainly want to know how + to setup MFA. If you're using the included :file:`sshd_config` and :file:`pam.d/ssh` templates unmodified, + which you are if you've followed the installation section, this will just work out of the box so you may skip + over the details and jump to :ref:`immediate_mfa_howto`. + +sshd_config snippet +------------------- + +Let's take the last few lines of the :file:`ssh_config` file and explain them step by step. These are where the +MFA logic is implemented. We've left the comments that can be found in the template, for clarity. + +.. code-block:: shell + + # If 2FA has been configured for root, we force pubkey+PAM for it. If this is the case + # on your system, uncomment the next two lines (see + # https://ovh.github.io/the-bastion/installation/advanced.html#fa-root-authentication) + #Match User root + # AuthenticationMethods publickey,keyboard-interactive:pam + +As explained in the comments within the file, this section (commented by default) refers to the MFA that can be +configured on the ``root`` account to protect The Bastion's own system. This is out of the scope of this documenation +section, as we're focusing on the users MFA here, so refer to the :ref:`installation/advanced:2fa root authentication` +section if that's what you want to achieve. + +.. code-block:: shell + + # Unconditionally skip PAM auth for members of the bastion-nopam group + Match Group bastion-nopam + AuthenticationMethods publickey + +The snipper above tells the SSH server to NOT rely on PAM (hence disable MFA) for accounts that are part of the +``bastion-nopam`` group. This is an internal group that is used for accounts whose MFA setup has been set to +bypass PAM authentication, with the following command: + +.. code-block:: none + :emphasize-lines: 1 + + bssh --osh accountModify --account robot-sync --pam-auth-bypass yes + ╭──ac777d06bec9───────────────────────────────────────────the-bastion-3.12.00─── + │ ▶ modify the configuration of an account + ├─────────────────────────────────────────────────────────────────────────────── + │ Bypassing sshd PAM auth usage for this account... + │ ... done, this account will no longer use PAM for authentication + ╰─────────────────────────────────────────────────────────────── + +This way, the account ``robot-sync`` will fall into the above configuration section ``Match`` case and end up +only using classic ``publickey`` authentication, hence no MFA. As MFA is only meaningful for humans, use this setting +for accounts that are used by any automated process you might have that interact with the bastion (for example using +its :doc:`/using/api`). + +.. code-block:: shell + + # if in one of the mfa groups AND the osh-pubkey-auth-optional group, use publickey+pam OR pam + Match Group mfa-totp-configd,mfa-password-configd Group osh-pubkey-auth-optional + AuthenticationMethods publickey,keyboard-interactive:pam keyboard-interactive:pam + +The snippet above tells SSH that for accounts having an authentication factor configured, namely either a TOTP or +a password, and having the "public key is optional" flag, set by ``--osh accountModify --pubkey-auth-optional``, +implies that those accounts can either authenticate through public key and an additional factor (through PAM), +or through PAM only. In essence these accounts may use only a password, or a TOTP, or both, without having a +public key in addition to the other factors. Hence, this is not MFA per-se, but is an additional functionaly available +should you need this in your environment. You may remove (or comment) the two lines above if you're confident you'll +never require the `pubkey-auth-optional` feature. + +.. code-block:: shell + + # if in one of the mfa groups, use publickey AND pam + Match Group mfa-totp-configd,mfa-password-configd + AuthenticationMethods publickey,keyboard-interactive:pam + +The snippet above is the core of the mandatory MFA configuration of the SSH server: it instructs the SSH server to +authenticate accounts that have at least one MFA factor configured with their public key first, then hand over the +authentication phase to PAM to check the additional factors. + +.. code-block:: shell + + # by default, always ask the publickey (no PAM) + Match All + AuthenticationMethods publickey + +Finally, the snippet above is for the general case, i.e. accounts not having MFA configured, in which case they're +authenticated using their public key only. + +PAM ssh snippet +--------------- + +The template is `heavily commented`, line by line, please have a look at it if you want to know more. + +.. _immediate_mfa_howto: + +How to use Immediate MFA +************************ + +If you want to setup immediate MFA, you'll need to setup the SSH server and PAM configurations correctly, as explained +above. If you installed the provided templates for both (which is the default), you're good to go. + +You may want either to enable MFA for *all* the accounts existing on your bastion, or only a subset of these users, +read on the proper section below for each case. + +Requiring all users to setup their MFA +-------------------------------------- + +To ensure no user can use their account without configuring their MFA first, you have to set the ``accountMFAPolicy`` +option of :file:`bastion.conf` to either ``any-required``, ``totp-required`` or ``password-required``. Detailed +information about this configuration setting is available +:ref:`here `. + +When this setting is configured to any of the 3 above values, no interaction will be allowed on the bastion (such as +using plugins or connecting to a remote asset) as long as the user didn't set up their MFA: + +.. code-block:: none + + bssh --osh selfListAccesses + │ + │ ⛔ Sorry johndoe, but you need to setup the Multi-Factor Authentication before using this bastion, please use either the `--osh selfMFASetupPassword' or the `--osh selfMFASetupTOTP' option, at your discretion, to do so + +The only allowed ``--osh`` commands allowed in such a case are ``help``, ``info`` and the two ones referenced in the +above error message, precisely to be able to setup the MFA on the account. + +In this mode, if you want to exclude a few accounts from requiring MFA (if you have accounts that are used by +automation or any other M2M workflow), you can do so using ``accountModify --pam-auth-bypass yes``. + +.. _immediate_mfa_subset_users: + +Requiring only a subset of users to setup their MFA +--------------------------------------------------- + +If instead of forcing all users to require MFA, you want to require a precise subset of users to have MFA, you should +leave the ``accountMFAPolicy`` to ``enabled``, and set the requirement flag on a per-account basis. This can be +done using ``accountModify --mfa-password-required yes`` and/or ``accountModify --mfa-totp-required yes``. If you +set both flags on the same account, the bastion will require both factors to be set and provided on authentication, +in addition to publickey authentication. In this case, 3 authentication factors would be required. This is why we +call it *MFA* instead of *2FA*: the number of additional factors you want is configurable. + +.. _jit_mfa: + +JIT MFA +======= + +This method implements MFA checking right before an action is allowed, depending on the bastion policy, instead of +requiring it at the ingress authentication stage. + +.. note:: + + Use this method if you want to enable MFA on a per-action basis. In this case, The Bastion will decide whether + providing additional authentication factors is required right before a specific action is requested (such as + connection to a given remote asset, or execution of a subset of ``--osh`` commands). + You may also want to use this method if for some reason you can't setup the :file:`sshd_config` file + as required by the *Immediate MFA* method + +Note that the different ways detailed below can be cumulated: you might want to enable MFA for a few plugins, along +with enabling it for sensitive remote hosts present in specific bastion groups, in addition to a few sensitive +accounts that would require it no matter what. + +.. _jit_mfa_sshd_config: + +Proper setup of sshd_config +*************************** + +To use `JIT MFA`, your first have to disable `Immediate MFA`, as is the default if you're using the provided +configuration template for your SSH server (which you are if you followed the default installation steps). +You'll need to comment out two lines within the :file:`/etc/ssh/sshd_config` file, these are located near the +end of the file: + +.. code-block:: shell + + # if in one of the mfa groups, use publickey AND pam + #Match Group mfa-totp-configd,mfa-password-configd + # AuthenticationMethods publickey,keyboard-interactive:pam + +You'll need to reload the SSH daemon for this to be taken into account. The next subsections explain how to setup +policies depending on the actions you want to protect through `JIT MFA`. + +On a per-plugin basis +********************* + +First ensure you've followed the :ref:`jit_mfa_sshd_config`. + +To force MFA for a plugin, you may add the ``mfa_required`` option to its configuration. This configuration parameter +allows 4 values: + +- `any`, in which case MFA is required with any supported factor (currently either password or TOTP) +- `password`, in which case a password is required in addition to publickey authentication +- `totp`, in which case a TOTP is required in addition to publickey authentication +- `none`, in which case no MFA is required (which is the default if the ``mfa_required`` setting is omitted) + +To enable MFA for the ``adminSudo`` plugin, for example, you may add: + +.. code-block:: shell + + { + "mfa_required": "any" + } + +to the :file:`/etc/bastion/plugin.adminSudo.conf` file. Please ensure that this file is readable by the +``bastion-users`` system group (as all :file:`/etc/bastion/plugin.*.conf` files should be), so that the code running +under the bastion users permissions can read it. + +When configured like this, usage of the adminSudo plugin, in our example, will trigger the validation of additional +authentication factors. +Note that for this to work, you must have the :file:`/etc/pam.d/ssh` file set up correctly, +as we're using PAM for this. The provided template is advised, and you're already using it if you followed the +default installation steps. +If you are not sure you're using the provided template, you may compare your current :file:`/etc/pam.d/ssh` file +with the proper template for your distro, which can be found in :file:`/opt/bastion/etc/pam.d/sshd.*`. + +As you see, the MFA phase will be fired up for this plugin, but not for the ``info`` plugin for example: + +.. code-block:: none + :emphasize-lines: 1,7 + + bssh --osh adminSudo + As this is required to run this plugin, entering MFA phase for johndoe. + Your account has Multi-Factor Authentication enabled, an additional authentication factor is required (password). + Your password expires on 2023/10/31, in 89 days + Password: ^C + + bssh --osh info + ╭──ac777d06bec9───────────────────────────────────────────the-bastion-3.12.00─── + │ ▶ information + ├─────────────────────────────────────────────────────────────────────────────── + │ You are johndoe + [...] + +On a per-group basis +******************** + +First ensure you've followed the :ref:`jit_mfa_sshd_config`. + +If you want to ensure that MFA is required to connect to a remote host through a bastion group, +you should tag this group to require MFA. To do this, use the ``groupModify`` command: + +.. code-block:: none + :emphasize-lines: 1,9,18 + + guybrush@bastion1(master)> groupModify --group securegroup --mfa-required any + ╭──ac777d06bec9───────────────────────────────────────────the-bastion-3.12.00─── + │ ▶ modify the configuration of a group + ├─────────────────────────────────────────────────────────────────────────────── + │ Modifying mfa-required policy of group... + │ ... done, policy is now: any + ╰───────────────────────────────────────────────────────────────── + + guybrush@bastion1(master)> groupInfo --group securegroup + ╭──ac777d06bec9───────────────────────────────────────────the-bastion-3.12.00─── + │ ▶ group info + ├─────────────────────────────────────────────────────────────────────────────── + │ Group securegroup's Owners are: guybrush + [...] + │ ❗ MFA Required: when connecting to servers of this group, users will be asked for an additional authentication factor + [...] + + guybrush@bastion1(master)> ssh root@127.1.2.3 + │ Welcome to bastion1, guybrush, your last login was 00:00:27 ago (Wed 2023-08-02 15:36:03 UTC) from 172.17.0.1(172.17.0.1) + [...] + + will try the following accesses you have: + - group-member of securegroup with ED25519-256 key SHA256:94yETEnnWUy9yTG1dgAdXgunq6zzJPjlddFXjUH0Czw [2023/03/03] (MFA REQUIRED: ANY) + + As this is required for this host, entering MFA phase for guybrush. + Your account has Multi-Factor Authentication enabled, an additional authentication factor is required (password). + Your password expires on 2023/10/31, in 89 days + Password: + +As you see, after setting the flag on the group, attempting to access an asset that is part of the group (see +``groupListServers``) will require MFA. + +.. note:: + + If an account has access to an asset via several groups, MFA will be required if at least one group requires it. + Hence, a good way to ensure that all connections to an asset will require MFA would be to list the + SSH keys on the remote server, match those to groups on the bastion, and ensure they all have ``--mfa-required`` enabled. + +On a per-account basis +********************** + +You may also use this method to enable MFA on a per-account basis (as is possible with the `Immediate MFA` method). + +To do this, you should follow the same steps than are outlined in the :ref:`immediate_mfa_subset_users` subsection of the `Immediate MFA` setup. + +The only difference will be in your :file:`sshd_config` file, as for `JIT MFA` your should ensure you've followed the :ref:`jit_mfa_sshd_config`. + +In the case of `Immediate MFA`, the uncommented :file:`sshd_config` file block asks the SSH server to hand over authentication to PAM, hereby +requiring MFA at the authentication phase. For the `JIT MFA` on a per-account basis, this configuration is disabled, but the bastion code, after the +authentication phase is over, verifies whether the account requires to provide additional authentication factors, and triggers a PAM call if this +is the case. + +Bypassing MFA for automated workflows +************************************* + +If you have accounts that are used for automation, you'll want to exclude them from requiring MFA. + +To do this, use ``--osh accountModify --mfa-password-required bypass --mfa-totp-required bypass``. Accounts +with this setting will no longer require to enter additional credentials even when the policy of `JIT MFA` would +require them to. + +Additional information +====================== + +MFA and interactive mode +************************ + +When using the interactive mode, and `JIT MFA`, attempting to conduct an action that requires MFA will trigger the MFA authentication phase, as expected. + +However, when multiple MFA-required operations are to be done back to back, as is often the case when interactive mode +is used, the MFA authentication phase will be triggered for each and every action, which can be cumbersome. + +As long as :ref:`administration/configuration/bastion_conf:interactivemodeproactivemfaenabled` is true, users can use the **mfa** command in interactive +mode, to trigger the MFA authentication phase proactively, and enter an elevated session that will not require to enter MFA again. This elevated session +will expire after :ref:`administration/configuration/bastion_conf:interactivemodeproactivemfaexpiration` seconds (15 minutes by default). Users can exit +the elevated session manually by typing **nomfa**. + +Here is how it looks like: + +.. code-block:: none + :emphasize-lines: 1,8,12,18,24,27 + + bssh -i + + Welcome to bastion1 interactive mode, type `help' for available commands. + You can use and for autocompletion. + You'll be disconnected after 60 seconds of inactivity. + Loading... 90 commands and 0 autocompletion rules loaded. + + guybrush@bastion1(master)> mfa + As proactive MFA validation has been requested, entering MFA phase. + Your account has Multi-Factor Authentication enabled, an additional authentication factor is required (password). + Your password expires on 2023/10/31, in 88 days + Password: + pamtester: successfully authenticated + Proactive MFA enabled, any command requiring MFA from now on will not ask you again. + This mode will expire in 00:15:00 (Thu 2023-08-03 12:35:08 UTC) + To exit this mode manually, type 'nomfa'. + + guybrush@bastion1(master)[MFA-OK]> groupAddServer + ╭──ac777d06bec9───────────────────────────────────────────the-bastion-3.12.00─── + │ ▶ adding a server to a group + ├─────────────────────────────────────────────────────────────────────────────── + [...] + + guybrush@bastion1(master)[MFA-OK]> nomfa + Your proactive MFA validation has been forgotten. + + guybrush@bastion1(master)> + + +As you seen, once ``mfa`` has been entered and the MFA validated, the prompt changes to ``[MFA-OK]`` implying that +any command usually requiring MFA will not ask for it again (such as ``groupAddServer`` in the above example, as +we've configured it to). We then explicitely exit the MFA elevated session by entering ``nomfa``. + +MFA and --osh batch +******************* + +The :doc:`/plugins/open/batch` plugin is useful to enter several ``--osh`` commands in a batch way. However, if +any of those commands require MFA, it would ask us repeatedly for our MFA, which can be cumbersome. + +To avoid this behavior, and if you know that some of the commands you want to use in batch more will require MFA, +you may use the ``--proactive-mfa`` option to the bastion, which will ask for your MFA *before* executing the +:doc:`/plugins/open/batch` plugin, and any command requiring MFA will not ask for it again: + +.. code-block:: none + :emphasize-lines: 1,6 + + bssh --proactive-mfa --osh batch + + As proactive MFA has been requested, entering MFA phase for guybrush. + Your account has Multi-Factor Authentication enabled, an additional authentication factor is required (password). + Your password expires on 2023/11/01, in 89 days + Password: + pamtester: successfully authenticated + ╭──ac777d06bec9───────────────────────────────────────────the-bastion-3.12.00─── + │ ▶ batch + ├─────────────────────────────────────────────────────────────────────────────── + │ Feed me osh commands line by line on stdin, I'll execute them sequentially. + │ Use 'exit', 'quit' or ^D to stop. + │ --- waiting for input + [...] + diff --git a/_sources/administration/security_advisories.rst.txt b/_sources/administration/security_advisories.rst.txt new file mode 100644 index 0000000..31f8ef0 --- /dev/null +++ b/_sources/administration/security_advisories.rst.txt @@ -0,0 +1,13 @@ +Security Advisories +=================== + +This section contains all the security advisories since The Bastion has been published. + +If you find any behavior or bug that you suspect might have a security impact, please +`report it here `_. + +.. toctree:: + :maxdepth: 1 + :caption: CVE List + + security_advisories/cve_2023_45140.rst diff --git a/_sources/administration/security_advisories/cve_2023_45140.rst.txt b/_sources/administration/security_advisories/cve_2023_45140.rst.txt new file mode 100644 index 0000000..2d9310e --- /dev/null +++ b/_sources/administration/security_advisories/cve_2023_45140.rst.txt @@ -0,0 +1,79 @@ +============== +CVE-2023-45140 +============== + +- ``Severity``: **4.8** (CVSS V3) +- ``Vector: CVSS:3.1/AV:N/AC:L/PR:H/UI:R/S:C/C:L/I:L/A:N`` +- ``Affected versions``: from 3.0.0 included to 3.14.15 excluded +- ``Patched versions``: 3.14.15 and up + +`This advisory is also available online `_. + +Summary +======= + +SCP and SFTP plugins don't honor group-based and account-based JIT MFA. + +Details +======= +Establishing a SCP/SFTP connection through The Bastion via a group access where MFA is enforced does not ask for additional factor. This abnormal behavior only applies to `per-group-based JIT MFA `_ and `JIT MFA on a per-account basis `_. + +Other MFA setup types, such as `Immediate MFA `_ and `JIT MFA on a per-plugin basis `_ are not affected. + +Normal SSH access (i.e. not SCP nor SFTP) is not affected. + +How to reproduce for group-based JIT MFA +======================================== +- Create a group +- Apply ``groupModify --mfa-required any`` to this group +- Grant SSH access to someone via this group on a given IP +- Grant ``scp`` download right (or ``sftp`` right) to the same person via this group on the same IP +- This group should now force MFA for any connection of the person allowed through the group's rights set. This is the case for SSH, but not for SCP or SFTP as would be expected. + +How to reproduce for account-based JIT MFA +========================================== +- Create an account +- Apply ``accountModify --personal-egress-mfa-required any`` to this account +- Grant a personal SSH access to this account on a given IP +- Grant ``scp`` download right (or ``sftp`` right) to the same account via their personal access on the same IP +- This account should now have forced MFA for any egress connection allowed through their personal rights set. This is the case for SSH, but not for SCP or SFTP as would be expected. + +Impact for group-based JIT MFA +============================== +For an actor to be able to bypass MFA for scp/sftp to a given remote server, ALL the following conditions must apply: + +- The target server must be part of a group (and have the egress group's public key trusted in its :file:`authorized_keys` file) +- The group must have JIT MFA enabled on it (through ``groupModify --mfa-required any``) +- The actor must have an account on the bastion +- The actor must be a member of the group (granted by the groups's gatekeepers) +- scp and/or sftp must be globally enabled on the bastion (this is the default) +- scp and/or sftp must be explicitly allowed to the given remote server through the group (granted by the groups's aclkeepers) + +When all conditions above apply, the actor would be able to use scp or sftp on the target server without requiring to provide an additional factor where it should. + +Impact for account-based JIT MFA +================================ +For an actor to be able to bypass MFA for scp/sftp to a given remote server, ALL the following conditions must apply: + +- The target server must be part of the actor's account personal accesses (and have the account's egress public key trusted in its :file:`authorized_keys` file) +- The account must have JIT MFA enabled on it (through ``accountModify --personal-egress-mfa-required any``) +- scp and/or sftp must be globally enabled on the bastion (this is the default) +- scp and/or sftp must be explicitly allowed to the given remote server through this account's personal accesses (granted by either ``selfAddPersonalAccess`` or ``accountAddPersonalAccess``) + +When all conditions above apply, the actor would be able to use scp or sftp on the target server without requiring to provide an additional factor where it should. + +Mitigation +========== +If you don't use the `per-group-based JIT MFA `_ on any of your groups (through ``groupModify --mfa-required``), and don't use the `JIT MFA on a per-account basis `_ (through ``accountModify --personal-egress-mfa-required``), you don't need to mitigate the issue as you don't use the impacted feature (see above for impact details). + +Otherwise, if you can't immediately upgrade to v3.14.15 or more recent, and you feel that the aforementioned impacts are important enough in your environment, you may choose to temporarily disable the ``scp`` and ``sftp`` plugins globally on the bastion, by setting ``"disabled": true`` in these plugins configuration files, which can be found in :file:`/etc/bastion/plugin.scp.conf` and :file:`/etc/bastion/plugin.sftp.conf` respectively. If these files don't exist, create them with the contents as ``{ "disabled": true }``. They should be readable by anyone but modifiable only by root (i.e. ``chmod 664; chown root:root``) + +Timeline +======== + +- 2023-10-06: security bug report filed on GitHub +- 2023-10-06: bug report accepted and confirmed as having a security impact +- 2023-10-11: CVE ID requested +- 2023-10-11: CVE ID assigned +- 2023-11-07: fix pushed to a private fork for review +- 2023-11-08: v3.14.15 released with the fix diff --git a/_sources/development/setup.rst.txt b/_sources/development/setup.rst.txt new file mode 100644 index 0000000..e009265 --- /dev/null +++ b/_sources/development/setup.rst.txt @@ -0,0 +1,190 @@ +Environment setup +================= + +.. contents:: + +This documentation section outlines the few steps needed to build a development environment for The Bastion, +easing code modification, tests, checks, and ultimately, pull requests. + +Available tools +*************** + +The provided :file:`docker/devenv/run-tool.sh` script will build a development docker for you, under which it'll +run several tools. Your local git folder will be mounted as a volume inside this docker so that it can +access the files, and potentially modify them (such as for ``perltidy``). + +The supported tools are as follows: + +.. code-block:: none + :emphasize-lines: 1 + + Usage: ./docker/devenv/run-tool.sh COMMAND [OPTIONS] + + COMMAND may be one of the following: + + tidy [FILES..] runs perltidy on several or all the Perl source files, modifying them if needed + tidycheck [FILES..] runs perltidy in dry-run mode, and returns an error if files are not tidy + perlcritic runs perlcritic on all the Perl source files + shellcheck [FILES..] runs shellcheck on all the shell source files + lint runs tidy, perlcritic and shellcheck on all files in one command + doc generates the documentation + sphinx-view-objects shows the named objects of the Sphinx documentation that can be referenced + rebuild forces the rebuild of the devenv docker image that is needed to run all the above commands + run spawn an interactive shell to run any arbitrary command in the devenv docker + doc-serve starts a local HTTP python server on PORT to view generated documentation + +Before submitting a pull request, you'll need at minimum to run ``lint``. It might be a good idea to setup a +git pre-commit hook to do this on modified files, see below. + +Git pre-commit hook +******************* + +Some lint checks are enforced through GitHub Actions, but it'll save you a lot of back-and-forth if you ensure that +these checks are passing locally on your development environment. + +To this effect, you'll need to setup pre-commit hooks on your local copy of the git repository, so that your code +is automatically checked by ``perlcritic``, ``perltidy`` and ``shellcheck`` each time you commit. + +If you previously cloned the repository with such a command: + +.. code-block:: none + :emphasize-lines: 1 + + git clone https://github.com/ovh/the-bastion + +Then you can copy the provided :file:`pre-commit` script into your local :file:`.git` folder: + +.. code-block:: none + :emphasize-lines: 1 + + cp contrib/git/pre-commit .git/hooks/pre-commit + +To verify that it works checkout a new test branch and add two dummy files like this: + +.. code-block:: none + :emphasize-lines: 1-5 + + git checkout -B mybranch + printf "%b" "#! /usr/bin/env bash\nunused=1\n" > bin/shell/dummy.sh + printf "%b" "#! /usr/bin/env perl\nsub dummy { 1; };\n" > lib/perl/dummy.pm + git add bin/shell/dummy.sh lib/perl/dummy.pm + git commit -m dummy + + *** Checking shell files syntax using system shellcheck + `-> bin/shell/dummy.sh + + In bin/shell/dummy.sh line 2: + unused=1 + ^----^ SC2034: unused appears unused. Verify use (or export if used externally). + + `-> [ERR.] + + ERROR: shell-check failed on bin/shell/dummy.sh + *** Checking perl tidiness + `-> lib/perl/dummy.pm + ./lib/perl/dummy.pm ./lib/perl/dummy.pm.tdy differ: char 38, line 2 + --- ./lib/perl/dummy.pm 2023-10-03 08:19:55.605950307 +0000 + +++ ./lib/perl/dummy.pm.tdy 2023-10-03 08:20:43.618577295 +0000 + @@ -1,2 +1,2 @@ + #! /usr/bin/env perl + -sub dummy { 1; }; + +sub dummy { 1; } + + ERROR: perl tidy failed on lib/perl/dummy.pm + + !!! COMMIT ABORTED !!! + If you want to commit nevertheless, use -n. + +As you see, the checks are running before the commit is validated and abort it should any check fail. + +Running integration tests +************************* + +Using Docker +------------ + +Functional tests use ``Docker`` to spawn an environment matching a bastion install. +One of the docker instances will be used as client, which will connect to the other instance +which is used as the bastion server. The client instance sends commands to the server instance +and tests the return values against expected output. + +To test the current code, use the following script, which will run ``docker build`` and launch the tests: + +.. code-block:: none + :emphasize-lines: 1 + + tests/functional/docker/docker_build_and_run_tests.sh + +Where target is one of the supported OSes. Currently only Linux targets are supported. +You'll get a list of the supported targets by calling the command without argument. + +For example, if you want to test it under Debian (which is a good default OS if you don't have any preference): + +.. code-block:: none + :emphasize-lines: 1 + + tests/functional/docker/docker_build_and_run_tests.sh debian12 + +The full tests usually take 25 to 50 minutes to run, depending on your hardware specs. +If you want to launch only a subset of the integration tests, you may specify it: + +.. code-block:: none + :emphasize-lines: 1 + + tests/functional/docker/docker_build_and_run_tests.sh debian12 --module=320-base.sh + +Other options are supported, and passed through as-is to the underlying test script, use ``--help`` as below to +get the list (the output in this documentation might not be up to date, please actually launch it yourself +to get up-to-date information): + +.. code-block:: none + :emphasize-lines: 1 + + tests/functional/launch_tests_on_instance.sh --help + + Usage: /home/user/bastion/tests/functional/launch_tests_on_instance.sh [OPTIONS] + + Test Options: + --skip-consistency-check Speed up tests by skipping the consistency check between every test + --no-pause-on-fail Don't pause when a test fails + --log-prefix=X Prefix all logs by this name + --module=X Only test this module (specify a filename found in `functional/tests.d/`), can be specified multiple times + + Remote OS directory locations: + --remote-etc-bastion=X Override the default remote bastion configuration directory (default: /etc/bastion) + --remote-basedir=X Override the default remote basedir location (default: /home/user/bastion) + + Specifying features support of the underlying OS of the tested bastion: + --has-ed25519=[0|1] Ed25519 keys are supported (default: 1) + --has-mfa=[0|1] PAM is usable to check passwords and TOTP (default: 1) + --has-mfa-password=[0|1] PAM is usable to check passwords (default: 0) + --has-pamtester=[0|1] The `pamtester` binary is available, and PAM is usable (default: 1) + --has-piv=[0|1] The `yubico-piv-tool` binary is available (default: 1) + --has-sk=[0|1] The openssh-server supports Secure Keys (FIDO2) (default: 0) + +Without Docker +-------------- + +.. note:: + + This method is discouraged, prefer using the Docker method above when possible + +You can test the code against a BSD (or any other OS) without using Docker, by spawning a server +under the target OS (for example, on a VM), and installing the bastion on it. + +Then, from another machine, run: + +.. code-block:: none + :emphasize-lines: 1 + + test/functional/launch_tests_on_instance.sh [outdir] + +Where ``IP`` and ``port`` are the information needed to connect to the remote server to test, +``remote_user_name`` is the name of the account created on the remote bastion to use for the tests, +and ``ssh_key_path`` is the private SSH key path used to connect to the account. +The ``outdir`` parameter is optional, if you want to keep the raw output of each test. + +This script is also the script used by the Docker client instance, +so you're sure to get the proper results even without using Docker. + +Please do **NOT** run any of those tests on a production bastion! diff --git a/_sources/development/tests.rst.txt b/_sources/development/tests.rst.txt new file mode 100644 index 0000000..e167212 --- /dev/null +++ b/_sources/development/tests.rst.txt @@ -0,0 +1,180 @@ +Writing tests +============= + +.. contents:: + +When modifying code, adding features or fixing bugs, you're expected to write one or more tests to ensure that +the feature your adding works correctly, or that the bug you've fixed doesn't come back. + +Integration tests modules live in the :file:`tests/functional/tests.d` folder. +You may either add a new file to test your feature, or modify an existing file. + +These modules are shell scripts, and are sourced by the main integration test engine. Having a look at one of +these modules will help you understand how they work, the :file:`tests/functional/tests.d/320-base.sh` is a good +example you might want to look at. + +Example +------- + +Here is a simple test taken from :file:`320-base.sh`: + +.. code-block:: none + :caption: a simple test + + success help2 $a0 --osh help + contain "OSH help" + json .error_code OK .command help .value null + +A complete reference of such commands can be found below, but let's explain this example in a few words: + +The command ``success`` implies that we're running a new test command, and that we expect it to work (we might +also want to test invalid commands and ensure they fail as they should). +The tester docker will connect to the target docker (that is running the bastion code) as a bastion user, and +run the ``--osh help`` command there. This is expected to exit with a code indicating success (0), +otherwise this test fails. + +The output of the command, once run on the bastion, should contain the text ``OSH help``, or the test will fail. + +In the JSON output (see :doc:`/using/api`) of this command, we expect to find the ``error_code`` field set to ``OK``, +the ``command`` field set to ``help``, and the ``value`` field set to ``null``, or the test will fail. + +Running just this test will yield the following output: + +.. code-block:: none + :caption: a simple test output + + 00m04 [--] *** [0010/0021] 320-base::help2 (timeout --foreground 30 ssh -F /tmp/bastiontest.pgoA5h/ssh_config -i /tmp/bastiontest.pgoA5h/account0key1file user.5000@bastion_debian10_target -p 22 -- --json-greppable --osh help) + 00m05 [--] [ OK ] RETURN VALUE (0) + 00m05 [--] [ OK ] MUST CONTAIN (OSH help) + 00m05 [--] [ OK ] JSON VALUE (.error_code => OK) [ ] + 00m05 [--] [ OK ] JSON VALUE (.command => help) [ ] + 00m05 [--] [ OK ] JSON VALUE (.value => null) [ ] + +As you can see, this simple test actually checked 5 things: the return value, whether the output text contained +a given string, and 3 fields of the JSON output. + +Reference +--------- + +These are functions that are defined by the integration test engine and should be used in the test modules. + +Launch a test +************* + +run ++++ + +.. admonition:: syntax + :class: cmdusage + + - run + +This function runs a new test named ````, which will execute ```` on the tester docker. +Usually ```` will connect to the target docker (running the bastion code) using one of the test accounts, +and run a command there. + +A few accounts are preconfigured: + +- The main account ("account 0"): this one is guaranteed to always exist at all times, and is a bastion admin. + There are a few variables that can be referenced to use this account: + + - ``$a0`` is the ssh command-line to connect to the remote bastion as this account + - ``$account0`` is the account name, to be used in parameters of ``--osh`` commands where needed + +- A few secondary accounts that are created, deleted, modified during the tests: + + - ``$a1``, ``$a2`` and ``$a3`` are the ssh command-lines to connect to the remote bastion as these accounts + - ``$account1``, ``$account2`` and ``$account3`` are the accounts names + +- Another special non-bastion-account command exists: + + - ``$r0`` is the required command-line to directly connect to the remote docker on which the bastion code is running, + as root, with a bash shell. Only use this to modify the remote bastion files, such as config files, between tests + +A few examples follow: + +.. code-block:: none + :caption: running a few test commands + + run test1 $a0 --osh info + run test2 $a0 --osh accountInfo --account $account1 + run test3 $a1 --osh accountDelete --account $account2 + +Note that the ``run`` function just runs the given command, but doesn't check whether it exited normally, you'll +need other functions to verify this, see below. + +success ++++++++ + +.. admonition:: syntax + :class: cmdusage + + - success + +This function is exactly the same as the ``run`` command above, except that it expects the given ```` to +return a valid error code (zero). Most of the time, you should be using this instead of ``run``, except if you're +expecting the command to fail, in which case you should use ``run`` + ``retvalshouldbe``, see below. + +plgfail ++++++++ + +.. admonition:: syntax + :class: cmdusage + + - plgfail + +This function is exactly the same as the ``run`` command above, except that it expects the given ```` to +return an error code of 100, which is the standard exit value when an osh command fails. + +This function is equivalent to using ``run`` followed by ``retvalshouldbe 100`` (see below). + +Verify a test validity +********************** + +retvalshouldbe +++++++++++++++ + +.. admonition:: syntax + :class: cmdusage + + - retvalshouldbe + +Verify that the return value of a test launched right before with the ``run`` function is ````. +You should use this if you expect the previous test to return a non-zero value. + +Note that the ``success`` function is equivalent to using ``run`` followed by ``retvalshouldbe 0``. + +contain ++++++++ + +.. admonition:: syntax + :class: cmdusage + + - contain + - contain REGEX + +This function verifies that the output of the test contains a given ````. If you need to use a regex +to match the output, you can use the ``contain REGEX`` construction, followed by the regex. + +nocontain ++++++++++ + +.. admonition:: syntax + :class: cmdusage + + - nocontain + - nocontain REGEX + +This function does the exact opposite of the ``contain`` function just above, and ensure that a given text +or regex is NOT present in the output. + +json +++++ + +.. admonition:: syntax + :class: cmdusage + + - json [ ...] + +This function checks the JSON API output of the test, and validates that it contains the correct value for each +specified field. The ```` entries must be valid `jq` filters. diff --git a/_sources/faq.rst.txt b/_sources/faq.rst.txt new file mode 100644 index 0000000..5c72012 --- /dev/null +++ b/_sources/faq.rst.txt @@ -0,0 +1,172 @@ +=== +FAQ +=== + +"The Bastion", really? +====================== + +We've been using this software for quite a while at OVHcloud, and there it has always been known as "the bastion": +nobody ever bothered to find a fancy name for it. +So, when we decided to release it in opensource, the naming problem arose. +After going through some possible names, we realized that nothing would work, as everybody would keep +naming it "the bastion" anyway, so, we decided to call it just *The Bastion*. + +Why using common::sense? +======================== + +Because it's usually a good idea to ensure you use common::sense before writing code! +On a more serious note, this is almost like using ``strict`` and ``warnings``, +but with a very reduced memory footprint. +When you run a bastion with thousands of simultaneous active sessions with that many users, it starts to matter. + +Why Perl? +========= + +There is probably and endless list of why it's the perfect language for this, +and another similarly endless list of why Perl is completely irrelevant and other $COOL_LANGUAGE would be a better fit, +but some "why" reasons include: + +- It works everywhere, and most OSes have it installed by default +- Perl has this cool "taint" mode that adds security to untrusted program inputs, we use this on sensitive code +- One of the design choice of The Bastion has always been to be very close to the system, + leveraging some low-level Operating System functions, which are easier to interact with using a scripting language +- The Bastion has a loose origin from an old script written at OVHcloud in the early days, + back when the de-facto usual language used internally was Perl + +Why not using a PKI? +==================== + +Well, you can, of course! However this is a very centralized way of managing your accesses, +with all the power in the hands of whoever controls your CA. +It can be a highly successful if done very carefully, with a lot of security and processes around the +certificates delivery workflows. Managing a CA correctly is no joke and can bite you quite hard if done improperly. +This also happens to be a somewhat recent addition to OpenSSH, and if you have a lot of heterogeneous +systems to handle, this might be a no-go. +You can read more about this topic here: https://blog.ovhcloud.com/the-ovhcloud-bastion-part-1/ + +What does `osh` mean in ``--osh``? +================================== + +This has long been forgotten. Some people say it used to mean "Ovh SHell" at some point, +but nobody knows whether it's true or just a legend. + +What are the recommended hardware specifications? +================================================= + +They're actually quite low. Down to its basics, the bastion is merely a fancy wrapper around ``ssh``, +so if you have a device that handles ``ssh`` well, it'll handle the bastion just fine. + +Now to give you some data points, we've observed that 250 concurrent users take up 2.5 Gb of RAM (including +the operating system's own footprint, and the usual daemons such as auditd, syslog, etc.). +So a rule of thumb would be 1 Gb per 100 simultaneous sessions. +If you expect to get a lot of new connections per minute (not necessarily long-lived), +it's advised to use SSD drives however, as the bastion workload pattern for disk I/O is a lot of random seeks +to write logs and ttyrecs. Mechanical hard drives are very bad at this. + +.. _faq_docker: + +Can I run it under Docker in production? +======================================== + +Technically you can, but you have to think about what are the implications (this is true regardless +of the containerization technology). What's important to understand is that it adds another layer of abstraction, +and can give you a false sense of security. +If you either have the complete control of the host running Docker (and hardened it properly), +or you fully trust whoever is running the host for you, then this is fine. +Otherwise, *somebody* might have access to all your keys and you have no way to know or block it. + +Note that the provided Dockerfiles are a good start, but no volumes are defined. +To ensure that all the accounts don't disappear on a ``docker rm``, you would at least need to ensure that +``/home``, ``/etc/passwd``, ``/etc/shadow``, ``/etc/group``, ``/etc/gshadow`` are stored in a volume, +in addition to ``/etc/bastion`` and ``/root/.gpg``. +You'll also need an SSH server, obviously, and probably a ``syslog-ng`` daemon. + +.. _faq_existing_server: + +Can I install it on my already existing server? +=============================================== + +This is discouraged if your server is already doing something else, such as hosting a website, +handling your e-mails or running a database. + +From a security standpoint, it's a bad idea because if your server gets hacked due to one of +the other services you're hosting, the SSH keys could get compromised even if The Bastion itself has no security issue. + +This is also discouraged due to the design of The Bastion: being deeply intertwined with the OS it's running on, +it might make changes that seem intrusive from the point of view of other running services. +Such as creating and deleting system accounts and groups from time to time, modifying the PAM configuration, +or hardening the SSH client and server configurations system-wide, +which could break other services or workflows that expect to be running on a default (non-hardened) SSH configuration. + +.. _faq_jumphost: + +How to use The Bastion with the SSH ``ProxyCommand`` option? +============================================================ + +**tl;dr**: you can't. + +**Fast answer**: you can't, because The Bastion is not a proxy, nor what is often called an "ssh jumphost". +Granted, sometimes these are also called "bastions", hence the confusion. +Note that this also applies to the ``-J`` or ``JumpHost`` ssh option, which is just a simplified ``ProxyCommand``. + +**Long answer**: The Bastion is acting as a trusted party between you (the admin or the robot) and the server +of the infrastructure you need to access. To achieve this, when you use the bastion to connect to the server, +there are two distinct ssh connections present at the same time: + + - The ingress ssh connection, between you and the bastion. + For this connection your local private ssh key is used to authenticate yourself to the bastion + - The egress ssh connection, between the bastion and the remote server you need to access. + For this connection your bastion egress private ssh key (or a group egress private ssh key you're member of) + is used to authenticate the bastion to the remote server + +Those two connections are distinct, and the bastion logic merges those two so that you're under the impression +that you're directly connected to the remote server. There is no dynamic port forwarding happening on the bastion +to enable access to the remote server from your desktop, network-wise (which is what ``JumpHost`` does). + +Using ``ProxyCommand`` with the bastion doesn't make sense because with this option, your local ssh client expects +to talk the SSH dialect on the STDIN of the ProxyCommand you're giving, and it'll try to use your local SSH key +to authenticate you through it, which won't work as it's only used for the ingress connection. +However, when you use the usual bastion alias, in STDIN you have the remote server terminal directly, +all the SSH stuff has already been done. + +Attempting to summarize this a bit would be: ``ProxyCommand`` and ``JumpHost`` are useful when the server +you're trying to connect to can't be accessed *network-wise* from where you stand, and needs to be accessed +through some kind of proxy instead, where The Bastion's logic is to use two distinct SSH connections, +and two distinct authentication phases, with two distinct SSH keys (yours for the ingress connection, +and your bastion egress key for the egress connection). + +What is *session locking*? +========================== + +Session locking can be enabled in the global configuration, through the :ref:`idleLockTimeout` option. + +When enabled, the interactive SSH session will automatically lock itself after a defined amount of idle time. +Unlocking such a session can be done, but re-authentication is required, i.e. connecting to the bastion +from another console, and using the :doc:`/plugins/open/unlock` command. +Here, idle time is defined as keyboard input idle time, so even if a remote command might be running +(such as ``tail -f``), the connection will still be considered idle if no input is detected. This is by design. + +Such as configuration can be required by policy or regulations, in some sensitive environments, +to ensure opened connections are automatically cut off when unused. +Locking such sessions can be an alternative to cutting (see the :ref:`idleKillTimeout` option) as it gives +a chance to unlock the session before tearing the connection down. +Both can also be used, such as locking first, then tearing down after more time has passed without the session +being unlocked. Note that while a session is locked, any potentially running remote command will still be running, +as locking the session will just hide the normal console output, and prevent any input to be registered. +Unlocking the session will simply resume display to the console. +Session locking can be seen as the equivalent of a desktop screensaver, but for SSH interactive sessions. + +A locked session looks like this: + +.. image:: /img/locked_session.png + +Can I use Ansible over The Bastion? +=================================== + +Yes, you can, by using a wrapper available `here `_. + +Please note however that some Ansible modules may not use the builtin SSH command of Ansible, +which we override with our wrapper, but some other mechanism we can't hook into. +This is for example the case of the `network_cli` module of Ansible, which underneath uses Paramiko, +a Python library to handle SSH connections, which prevents our wrapper to be used (see +`this GitHub issue `_ for more information). diff --git a/_sources/index.rst.txt b/_sources/index.rst.txt new file mode 100644 index 0000000..9d7f325 --- /dev/null +++ b/_sources/index.rst.txt @@ -0,0 +1,107 @@ +===================================== +Welcome to The Bastion documentation! +===================================== + +.. warning:: + + This documentation is in a WIP status, some edges might be rough! + +Wait, what's a bastion exactly? (in 140-ish characters) +======================================================= + +A so-called **bastion** is a machine used as a single entry point by operational teams (such as sysadmins, developers, devops, database admins, etc.) to securely connect to other machines of an infrastructure, usually using `ssh`. + +The bastion provides mechanisms for *authentication*, *authorization*, *traceability* and *auditability* for the whole infrastructure. + +Just yet another SSH relayhost/jumphost/gateway? +************************************************ + +No, The Bastion is an entirely different beast. + +The key technical difference between those and The Bastion is that it strictly stands between you and the remote server, operating a protocol break in the process, which enables unique features such as tty recording, proper access auditability, builtin access and groups management commands, delegation of responsibilities all the way through, etc. + +Advanced uses even include doing other things than just SSHing to a remote server. + +Those wouldn't be possible with a "simple" jumphost. More technical details on the difference :ref:`here `. + +OK, tell me more! +================= + +This documentation is organized in several sections. The first one is a **PRESENTATION** of the main functionalities, principles, and use cases of the bastion. + +The second section explains the **INSTALLATION** procedure, including how to set up a quick playground using Docker if you want to get your hands dirty quickly. + +The third section focuses on the **USAGE** of the bastion, from the perspective of the different roles, such as bastion users, group owners, bastion admins, etc. + +The fourth section is about the proper **ADMINISTRATION** of the bastion itself. If you're about to be the person in charge of managing the bastion for your company, you want to read that one carefully! + +The fifth section is about **DEVELOPMENT** and how to write code for the bastion. If you'd like to contribute, this is the section to read! + +The sixth section is the complete reference of all the **PLUGINS** that are the commands used to interact with the bastion accounts, groups, accesses, credentials, and more. + +The unavoidable and iconic FAQ is also available under the **PRESENTATION** section. + +.. toctree:: + :maxdepth: 2 + :caption: Presentation + + presentation/principles + presentation/features + presentation/security + faq + +.. toctree:: + :maxdepth: 2 + :caption: Installation + + installation/basic + installation/advanced + installation/upgrading + installation/docker + installation/restoring_from_backup + +.. toctree:: + :maxdepth: 2 + :caption: Usage + + using/basics/index + using/piv + using/sftp_scp_rsync + using/http_proxy + using/api + using/specific_ssh_clients_tutorials/index + +.. toctree:: + :maxdepth: 2 + :caption: Administration + + administration/configuration/index + administration/logs + administration/mfa + administration/security_advisories + +.. toctree:: + :maxdepth: 2 + :caption: Development + + development/setup + development/tests + +.. _plugins: + +.. toctree:: + :maxdepth: 2 + :caption: Plugins + + plugins/admin/index.rst + plugins/group-aclkeeper/index.rst + plugins/group-gatekeeper/index.rst + plugins/group-owner/index.rst + plugins/open/index.rst + plugins/restricted/index.rst + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` diff --git a/_sources/installation/advanced.rst.txt b/_sources/installation/advanced.rst.txt new file mode 100644 index 0000000..796bb2d --- /dev/null +++ b/_sources/installation/advanced.rst.txt @@ -0,0 +1,530 @@ +===================== +Advanced Installation +===================== + +This section goes further in explaining how to setup your bastion. +You should have completed the :doc:`basic installation` first. + +.. _installadv_gpg: + +Encryption & signature GPG keys +=============================== + +.. note:: + + This section is a prequisite to both the :ref:`installadv_encryptrsync` and the + :ref:`installadv_backup` steps further down this documentation + +There are 2 pairs of GPG keys being used by the bastion: + +- The *bastion GPG key* + + * The **private** key is used by the **bastion** to **sign** the ttyrec files + * The **public** key is used by the **admins** to **verify** the signature and prove + non-repudiation and non-tampering of the ttyrec files + +- The *admins GPG key* + + * The **public** key is used by the **bastion** to **encrypt** the backups and the ttyrec files + * The **private** key is used by the **admins** to **decrypt** the backups when + a restore operation is needed, and the ttyrec files + +Generating the bastion GPG key +****************************** + +Generate a GPG key that will be used by the bastion to sign files, +this might take a while especially if the server is idle: + +.. code-block:: shell + :emphasize-lines: 1 + + /opt/bastion/bin/admin/setup-gpg.sh --generate + + gpg: directory `/root/.gnupg' created + gpg: Generating GPG key, it'll take some time. + + Not enough random bytes available. Please do some other work to give + the OS a chance to collect more entropy! (Need 39 more bytes) + ..........+++++ + gpg: /root/.gnupg/trustdb.gpg: trustdb created + gpg: key A4480F26 marked as ultimately trusted + gpg: done + gpg: checking the trustdb + gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model + gpg: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u + + Configuration file /etc/bastion/osh-encrypt-rsync.conf.d/50-gpg-bastion-key.conf updated: + 8<---8<---8<---8<---8<---8<-- + # autogenerated with /opt/bastion/bin/admin/setup-gpg.sh at Wed Mar 21 10:03:08 CET 2018 + { + "signing_key_passphrase": "************", + "signing_key": "5D3CFDFFA4480F26" + } + --->8--->8--->8--->8--->8--->8 + + Done. + +While it's working, you can proceed to the section below. + +Generating and importing the admins GPG key +******************************************* + +You should import on the bastion one or more **public** GPG keys that'll be used for encryption. +If you don't already have a GPG key for this, you can generate one. As this is the admin GPG key, +don't generate it on the bastion itself, but on the desk of the administrator (you?) instead. + +If you're running a reasonably recent GnuPG version (and the bastion does, too), +i.e. GnuPG >= 2.1.x, then you can generate an Ed25519 key by running: + +.. code-block:: shell + :emphasize-lines: 1-8 + + myname='John Doe' + email='jd@example.org' + bastion='mybastion4.example.org' + pass=$(pwgen -sy 12 1) + echo "The passphrase for the key will be: $pass" + gpg --batch --pinentry-mode loopback --passphrase-fd 0 --quick-generate-key "$myname <$email>" ed25519 sign 0 <<< "$pass" + fpr=$(gpg --list-keys "$myname <$email>" | grep -Eo '[A-F0-9]{40}') + gpg --batch --pinentry-mode loopback --passphrase-fd 0 --quick-add-key "$fpr" cv25519 encr 0 <<< "$pass" + + gpg: key 3F379CA7ECDF0537 marked as ultimately trusted + gpg: directory '/home/user/.gnupg/openpgp-revocs.d' created + gpg: revocation certificate stored as '/home/user/.gnupg/openpgp-revocs.d/3DFB21E3857F562A603BD4F83F379CA7ECDF0537.rev' + + +If you or the bastion is using an older version of GnuPG, or you are unsure and/or prefer compatibility +over speed or security, you can fallback to an RSA 4096 key: + +.. code-block:: shell + :emphasize-lines: 1-9 + + myname='John Doe' + email='jd@example.org' + bastion='mybastion4.example.org' + pass=`pwgen -sy 12 1` + echo "The passphrase for the key will be: $pass" + printf "Key-Type: RSA\nKey-Length: 4096\nSubkey-Type: RSA\nSubkey-Length: 4096\n" \ + "Name-Real: %s\nName-Comment: %s\nName-Email: %s\nExpire-Date: 0\n" \ + "Passphrase: %s\n%%echo Generating GPG key\n%%commit\n%%echo done\n" \ + "$myname ($bastion)" $(date +%Y) "$email" "$pass" | gpg --gen-key --batch + + The passphrase for the key will be: ************ + gpg: Generating GPG key + + Not enough random bytes available. Please do some other work to give + the OS a chance to collect more entropy! (Need 119 more bytes) + .....+++++ + + gpg: key D2BDF9B5 marked as ultimately trusted + gpg: done + +Of course, in both snippets above, adjust the ``myname``, ``email`` and ``bastion`` variables accordingly. +Write down the passphrase in a secure vault. All bastions admins will need it if they are to decrypt ttyrec files +later for inspection, and also decrypt the backup should a restore be needed. +When the key is done being generated, get the public key with: + +.. code-block:: shell + :emphasize-lines: 1 + + gpg -a --export "$myname <$email>" + +Copy it to your clipboard, then back to the bastion, paste it at the following prompt: + +.. code-block:: shell + :emphasize-lines: 1 + + /opt/bastion/bin/admin/setup-gpg.sh --import + +Also export the private admins GPG key to a secure vault (if you want the same key to be shared by the admins): + +.. code-block:: shell + :emphasize-lines: 1 + + gpg --export-secret-keys --armor "$myname <$email>" + +.. _installadv_encryptrsync: + +Rotation, encryption & backup of ttyrec files +============================================= + +.. note:: + + The above section :ref:`installadv_gpg` is a prerequisite to this one + +The configuration file is located in ``/etc/bastion/osh-encrypt-rsync.conf``. +You can ignore the ``signing_key``, ``signing_key_passphrase`` and ``recipients`` options, +as these have been auto-filled when you generated the GPG keys, by dropping configuration files +in the ``/etc/bastion/osh-encrypt-rsync.conf.d`` directory. +Any file there takes precedence over the global configuration file. + +Once you are done with your configuration, you might want to test it by running: + +.. code-block:: shell + + /opt/bastion/bin/cron/osh-encrypt-rsync.pl --config-test + +Or even go further by starting the script in dry-run mode: + +.. code-block:: shell + + /opt/bastion/bin/cron/osh-encrypt-rsync.pl --dry-run + + +.. _installadv_backup: + +Configuring keys, accounts & groups remote backup +================================================= + +.. note:: + + The above section :ref:`installadv_gpg` is a prerequisite to this one, otherwise your backups will NOT + be automatically encrypted, which is something you probably want to avoid. + +Everything that is needed to restore a bastion from backup (keys, accounts, groups, etc.) is backed up daily +in ``/root/backups`` by default. + +If you want to push these backups to a remote location, which is warmly advised, +you have to specify the remote location to ``scp`` the backup archives to. +The configuration file is ``/etc/bastion/osh-backup-acl-keys.conf``, +and you should specify the ``PUSH_REMOTE`` and ``PUSH_OPTIONS``. + +To verify that the script is correctly able to connect remotely (and also validate the remote hostkey), +start the script manually: + +.. code-block:: shell + :emphasize-lines: 1 + + /opt/bastion/bin/cron/osh-backup-acl-keys.sh + + Pushing backup file (/root/backups/backup-2020-05-25.tar.gz.gpg) remotely... + backup-2020-05-25.tar.gz.gpg + 100% 21MB 20.8MB/s 00:00 + +Also verify that the extension is ``.gpg``, as seen above, +which indicates that the script successfully encrypted the backup. + +Logs/Syslog +=========== + +It is advised to use syslog for The Bastion application logs. +This can be configured in ``/etc/bastion/bastion.conf`` with the parameter ``enableSyslog``. + +There is a default ``syslog-ng`` configuration provided, if you happen to use it. +The file can be found as ``etc/syslog-ng/conf.d/20-bastion.conf.dist`` in the repository. +Please read the comments in the file to know how to integrate it properly in your system. + +.. _installadv_ha: + +Clustering (High Availability) +============================== + +The bastions can work in a cluster, with N instances. In that case, there is one *master* instance, +where any modification command can be used (creating accounts, deleting groups, granting accesses), +and N-1 *slave* instances, where only *readonly* actions are permitted. Any of these instances may be +promoted, should the need arise. + +Note that any instance can be used to connect to infrastructures, so in effect all instances can always be used +at the same time. You may set up a DNS round-robin hostname, with all the instances IPs declared, +so that clients automatically choose a random instance, without having to rely on another external component +such as a load-balancer. Note that if you do this, you'll need all the instances to share the same SSH host keys. + +Before setting up the slave instance, you should have the two bastions up and running +(follow the normal installation documentation). Then, to set up the synchronization between the +instances, proceed as explained below. + +Allowing the master to connect to the slave +******************************************* + +On the slave, set the ``readOnlySlaveMode`` option in the ``/etc/bastion/bastion.conf`` file to ``true``: + +.. code-block:: shell + :caption: run this on the SLAVE: + :emphasize-lines: 1 + + vim /etc/bastion/bastion.conf + +This will instruct this bastion instance to deny any modification plugin, +so that changes can only be done through the master. + +Then, append the master bastion synchronization public SSH keyfile, +found in :file:`~root/.ssh/id_master2slave.pub` on the master instance, +to :file:`~bastionsync/.ssh/authorized_keys` on the slave, +with the following prefix: ``from="IP.OF.THE.MASTER",restrict`` + +Hence the file should look like this: + +.. code-block:: shell + :caption: run this on the SLAVE: + :emphasize-lines: 1 + + cat ~bastionsync/.ssh/authorized_keys + from="198.51.100.42",restrict ssh-ed25519 AAA[...] + +Pushing the accounts and groups files to the slave +************************************************** + +Check that the key setup has been done correctly by launching the following command under the ``root`` account: + +.. code-block:: shell + :caption: run this on the MASTER: + :emphasize-lines: 1 + + rsync -v --rsh "ssh -i /root/.ssh/id_master2slave" /etc/passwd /etc/group bastionsync@IP.OF.THE.SLAVE:/root/ + group + passwd + + sent 105,512 bytes received 8,046 bytes 75,705.33 bytes/sec + total size is 1,071,566 speedup is 9.44 + +If this works correctly, you'll have two new files in the :file:`/root` directory of the slave instance. +We'll need those for the next step, which is verifying that the UIDs/GIDs of the slave instance are matching +the master instance's ones. Indeed, the sync of the ``/etc/passwd`` and ``/etc/group`` files can have adverse effects +on a newly installed machine where the packages were not installed in the same order than on the master, hence having +possibly mismatching UIDs/GIDs for the same users/groups. + +The next step ensures these are matching between the master and the slave before actually enabling the synchronization. + +.. _installadv_ha_uidgidsync: + +Ensuring the UIDs/GIDs are in sync +********************************** + +Now that we have the master's :file:`/etc/passwd` and :file:`/etc/group` files in the slave's :file:`/root` folder, +we can use a helper script to check for the UIDs/GIDs matches between the master and the slave. +This script's job is to check whether there is any discrepancy, and if this is the case, generate another script, +tailored to your case, to fix them: + +.. code-block:: none + :caption: run this on the SLAVE: + :emphasize-lines: 1 + + /opt/bastion/bin/admin/check_uid_gid_collisions.pl --master-passwd /root/passwd --master-group /root/group --output /root/syncids.sh + WARN: local orphan group: local group 50 (with name 'staff') is only present locally, if you want to keep it, create it on the master first or it'll be erased + + There is at least one warning, see above. + If you want to handle them, you may still abort now. + Type 'YES' to proceed regardless. + +In the example above, the script warns us that some accounts or groups are only existing on the slave instance, +and not at all on the master. In this case, it's up to you to know what you want to do. If you choose to ignore it, +these accounts and groups will be erased on the first synchronization, as the master will push its own accounts and +groups to the slave instance. Such a discrepancy shouldn't happen as long as you're using the same OS and distro +on both sides. It may happen if you have installed more packages on the slave instance than on the master, as some +packages also create system groups or accounts. A possible fix is to install the same packages on the master, and/or +simply adding the account(s) and/or group(s) on the master, so that they're synchronized everywhere. + +If you type 'YES' or simply don't have any warnings, you should see something like this: + +.. code-block:: none + :caption: (output continued) + + Name collision on UID: master UID 38 exists on local but with a different name (master=gnats local=list) + -> okay, offsetting local UID 38 to 50000038 + Differing name attached to same UID: master UID 38 doesn't exist on local, but its corresponding name 'gnats' does, with local UID 41 + Name collision on UID: master UID 39 exists on local but with a different name (master=list local=irc) + -> okay, offsetting local UID 39 to 50000039 + [...] + You may now review the generated script (/root/syncids.sh) and launch it when you're ready. + Note that you'll have to reboot once the script has completed. + +The generated script is found at the location you've specified, which is :file:`/root/syncids.sh` if you used +the command-line we suggested above. Reviewing this script is important, as this is the one that will be making +UIDs/GIDs modification to your slave instance, as to sync them to the master's ones, including propagating these +changes on your filesystem, using ``chmod`` and ``chgrp`` commands. + +Once you're ready (note that you'll have to reboot the slave right after), you may run the generated script: + +.. code-block:: none + :caption: run this on the SLAVE: + :emphasize-lines: 1 + + bash /root/syncids.sh + + We'll change the UIDs/GIDs of files, when needed, in the following mountpoints: / /home /run /run/lock /run/snapd/ns /run/user/1001 /run/user/1001/doc /run/user/1001/gvfs + If you'd like to change this list, please edit this script and change the 'fslist' variable in the header. + Otherwise, if this sounds reasonable (e.g. there is no remotely mounted filesystem that you don't want us to touch), say 'YES' below: + +Please review the listed mountpoints (obviously, they'll be different than the ones above). As stated you may +edit the script to adjust them if needed. If any UID/GID needs to be changed to be in sync with the master, +the script will ensure the changes are propagated to the specified filesystems. You might want to exclude +network-mounted filesystems and such, if any. The script does its best to do this for you, but you should ensure +that it has got it right. + +Then, the script may list the daemons and running processes that it'll need to kill before doing the changes, +as Linux forbids changing UIDs/GIDs when they're used by a process. This is why a reboot is needed at the end. + +.. code-block:: shell + :caption: (output continued) + + The following processes/daemons will need to be killed before swapping the UIDs/GIDs: + USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND + kernoops 2484 0.0 0.0 11264 440 ? Ss Apr11 0:04 /usr/sbin/kerneloops + whoopsie 2467 0.0 0.0 253440 11860 ? Ssl Apr11 0:00 /usr/bin/whoopsie -f + colord 2227 0.0 0.0 249220 13180 ? Ssl Apr11 0:00 /usr/libexec/colord + geoclue 2091 0.0 0.1 905392 20268 ? Ssl Apr11 1:09 /usr/libexec/geoclue + rtkit 1789 0.0 0.0 153156 2644 ? SNsl Apr11 0:00 /usr/libexec/rtkit-daemon + syslog 1445 0.0 0.0 224548 4572 ? Ssl Apr11 0:02 /usr/sbin/rsyslogd -n -iNONE + systemd+ 1305 0.0 0.0 91016 4088 ? Ssl Apr11 0:00 /lib/systemd/systemd-timesyncd + + If you want to stop them manually, you may abort now (CTRL+C) and do so. + Press ENTER to continue. + +As stated, ensure that it's alright that these daemons are killed. You may want to terminate them manually +if needed, otherwise the script will simply send a ``SIGTERM`` to these processes. + +.. code-block:: shell + :caption: (output continued) + + [...] + Restoring SUID/SGID flags where needed... + [...] + UID/GID swapping done, please reboot now. + +As instructed, you may now reboot. + +.. note:: + + If you're currently restoring from a backup, you may stop here and resume + the :doc:`/installation/restoring_from_backup` procedure. + +Enabling the synchronization +**************************** + +Now that the master and the slave UIDs/GIDs are matching, we may enable the synchronization daemon: + +.. code-block:: shell + :caption: run this on the MASTER: + :emphasize-lines: 1 + + vim /etc/bastion/osh-sync-watcher.sh + +You may review the configuration, but the two main items to review are: + +- ``enabled``, which should be set to ``1`` +- ``remotehostlist``, which should contain the hosts/IPs list of the slave instances, separated by spaces + +If the synchronization daemon was not already enabled and started (i.e. this is the first slave instance +you're setting up for this master), then you should configure it to start it on boot, and you may also +start it manually right now: + +.. code-block:: shell + :caption: run this on the MASTER: + :emphasize-lines: 1-2 + + systemctl enable osh-sync-watcher + systemctl start osh-sync-watcher + +Otherwise, if the daemon is already enabled and active, you can just restart it so it picks up the new configuration: + +.. code-block:: shell + :caption: run this on the MASTER: + :emphasize-lines: 1 + + systemctl restart osh-sync-watcher + +Now, you can check the logs (if you configured ``syslog`` instead, which is encouraged, +then the logfile depends on your syslog daemon configuration. If you're using our bundled ``syslog-ng`` +configuration, the output is logged in :file:`/var/log/bastion/bastion-scripts.log`) + +.. code-block:: shell + :caption: run this on the MASTER: + :emphasize-lines: 1 + + tail -F /var/log/bastion/osh-sync-watcher.log + Apr 12 18:11:25 bastion1.example.org osh-sync-watcher.sh[3346532]: Starting sync! + Apr 12 18:11:25 bastion1.example.org osh-sync-watcher.sh[3346532]: 192.0.2.42: [Server 1/1 - Step 1/3] syncing needed data... + Apr 12 18:11:27 bastion1.example.org osh-sync-watcher.sh[3346532]: 192.0.2.42: [Server 1/1 - Step 1/3] sync ended with return value 0 + Apr 12 18:11:27 bastion1.example.org osh-sync-watcher.sh[3346532]: 192.0.2.42: [Server 1/1 - Step 2/3] syncing lastlog files from master to slave, only if master version is newer... + Apr 12 18:11:28 bastion1.example.org osh-sync-watcher.sh[3346532]: 192.0.2.42: [Server 1/1 - Step 2/3] sync ended with return value 0 + Apr 12 18:11:28 bastion1.example.org osh-sync-watcher.sh[3346532]: 192.0.2.42: [Server 1/1 - Step 3/3] syncing lastlog files from slave to master, only if slave version is newer... + Apr 12 18:11:30 bastion1.example.org osh-sync-watcher.sh[3346532]: 192.0.2.42: [Server 1/1 - Step 3/3] sync ended with return value 0 + Apr 12 18:11:39 bastion1.example.org osh-sync-watcher.sh[3346532]: All secondaries have been synchronized successfully + Apr 12 18:11:39 bastion1.example.org osh-sync-watcher.sh[3346532]: Watching for changes (timeout: 120)... + +Your new slave instance is now ready! + +Creating SSHFP DNS records +========================== + +If you want to use ``SSHFP`` to help authenticating your bastion public keys by publishing their checksum +in your DNS, here is now to generate the correct records: + +.. code-block:: shell + + awk 'tolower($1)~/^hostkey$/ {system("ssh-keygen -r bastion.name -f "$2)}' /etc/ssh/sshd_config + +You shall then publish them in your DNS. It is also a good idea to secure your DNS zone with DNSSEC, +but this is out of the scope of this manual. + +Hardening the SSH configuration +=============================== + +Using our SSH templates is a good start in any case. If you want to go further, there are a lot of online resources +to help you harden your SSH configuration, and audit a running SSHd server. +As the field evolves continuously, we don't want to recommend one particularly here, +as it might get out of date rapidly, but looking for `ssh audit `_ on GitHub +is probably a good start. Of course, this also depends on your environment, and you might not be able to harden +your SSHd configuration as much as you would like. + +Note that for The Bastion, both sides can be independently hardened: +the ingress part is handled in ``sshd_config``, and the egress part is handled in ``ssh_config``. + +2FA root authentication +======================= + +The bastion supports TOTP (Time-based One Time Password), to further secure high profile accesses. +This section covers the configuration of 2FA root authentication on the bastion itself. +TOTP can also be enabled for regular bastion users, but this is covered in another section. +To enable 2FA root authentication, run on the bastion: + +.. code-block:: shell + + script -c "google-authenticator -t -Q UTF8 -r 3 -R 15 -s /var/otp/root -w 2 -e 4 -D" /root/qrcode + +Of course, you can check the ``--help`` and adjust the options accordingly. +The example given above has sane defaults, but you might want to adjust if needed. +Now, flash this QR code with your phone, using a TOTP application. +You might want to copy the QR code somewhere safe in case you need to flash it on some other phone, +by exporting the ``base64`` version of it: + +.. code-block:: shell + + gzip -c /root/qrcode | base64 -w150 + +Copy this in your password manager (for example). You can then delete the :file:`/root/qrcode` file. + +You have then two configuration adjustments to do. + +- First, ensure you have installed the provided :file:`/etc/pam.d/sshd` file, or at least the corresponding line + to enable the TOTP pam plugin in your configuration. + +- Second, ensure that your :file:`/etc/ssh/sshd_config` file calls PAM for root authentication. + In the provided templates, there is a commented snippet to do it. The uncommented snippet looks like this: + +.. code-block:: shell + + # 2FA has been configured for root, so we force pubkey+PAM for it + Match User root + AuthenticationMethods publickey,keyboard-interactive:pam + +Note that first, the usual publickey method will be used, then control will be passed to PAM. +This is where the :file:`/etc/pam.d/sshd` configuration will apply. + +Now, you should be asked for the TOTP the next time you try to login through ssh as root. +In case something goes wrong with the new configuration, be sure to keep your already opened existing +connection to be able to fix the problem without falling back to console access. + +Once this has been tested, you can (and probably should) also protect the direct root console access +to your machine with TOTP, including a snippet similar to this one: + +.. code-block:: shell + + # TOTP config + auth [success=1 default=ignore] pam_google_authenticator.so secret=/var/otp/${USER} + auth requisite pam_deny.so + # End of TOTP Config + +inside your :file:`/etc/pam.d/login` file. + +Of course, when using TOTP, this is paramount to ensure your server is properly synchronized through NTP. diff --git a/_sources/installation/basic.rst.txt b/_sources/installation/basic.rst.txt new file mode 100644 index 0000000..6e96efb --- /dev/null +++ b/_sources/installation/basic.rst.txt @@ -0,0 +1,280 @@ +================== +Basic Installation +================== + +If you are just upgrading from a previous version, please read :doc:`upgrading` instead. + +0. Got Puppet? +============== + +We published a Puppet module to handle The Bastion configuration and prerequisites. +The GitHub repo is `here `_ and our module has been published to +`the Puppet forge `_. +Of course, its usage is completely optional, but if you choose to use it, +some of the below steps will be done by Puppet. Hence, you might want to only consider the following steps: + +- :ref:`install-basic_operating-system` +- :ref:`install-basic_get-the-code` +- :ref:`install-basic_encrypt-home` +- (Run Puppet) +- :ref:`install-basic_first-account` + +.. _install-basic_operating-system: + +1. Operating system +=================== + +.. warning:: + + The Bastion expects to be the only main service running on the server, + please see :ref:`this FAQ entry ` for more information. + +The following Linux distros are tested with each release, but as this is a security product, +you are *warmly* advised to run it on the latest up-to-date stable version of your favorite OS: + +- Debian 12 (Bookworm), 11 (Bullseye), 10 (Buster) +- RockyLinux 8.x, 9.x +- Ubuntu LTS 24.04, 22.04, 20.04, 18.04 +- OpenSUSE Leap 15.6\* + +\*: Note that these versions have no out-of-the-box MFA support, as they lack packaged versions of ``pamtester``, +``pam-google-authenticator``, or both. Of course, you may compile those yourself. +Any other so-called `modern` Linux version are not tested with each release, +but should work with no or minor adjustments. + +The following OS are also tested with each release: + +- FreeBSD/HardenedBSD 13.2\*\* + +\*\*: Note that these have partial MFA support, due to their reduced set of available ``pam`` plugins. +Support for either an additional password or TOTP factor can be configured, but not both at the same time. +The code is actually known to work on FreeBSD/HardenedBSD 10+, but it's only regularly tested under 13.2. + +Other BSD variants, such as OpenBSD and NetBSD, are unsupported as they have a severe limitation over the maximum +number of supplementary groups, causing problems for group membership and restricted commands checks, +as well as no filesystem-level ACL support and missing PAM support (hence no MFA). + +In any case, you are expected to install this on a properly secured machine (including, but not limited to: +``iptables``/``pf``, reduced-set of installed software and daemons, general system hardening, etc.). +If you use Debian, following the `CIS Hardening guidelines `_ is +a good start. We have `a tool `_ to check for compliance against these guidelines. +If you use Debian and don't yet have your own hardened template, this script should help you getting up to speed, +and ensuring your hardened host stays hardened over time, through a daily audit you might want to setup through cron. + +Great care has been taken to write secure, tested code, but of course this is worthless if your machine +is a hacker highway. Ensuring that all the layers below the bastion code (the operating system +and the hardware it's running on) is your job. + +2. Connect to your server as root +================================= + +You'll need to be connected to your server as root to perform the installation. If you're using root password +authentication through SSH to do so, note that during the installation, as the SSH server configuration +will be hardened, the SSH password authentication will be disabled server-wide. + +Hence, to access your server, please set up an SSH public key authentication instead of a password authentication, +and do so before proceeding with the next steps. Otherwise you might lose access to your own server once the +SSH hardening will be in effect, as password authentication will then be disabled. + +.. _install-basic_get-the-code: + +3. Get the code +=============== + +The bastion code usually lives under ``/opt/bastion``. +You can either use ``git clone`` directly, or get the tarball of the latest release. + +- Using :command:`git`: + +.. code-block:: shell + + git clone https://github.com/ovh/the-bastion /opt/bastion + git -C /opt/bastion checkout $(git -C /opt/bastion tag | tail -1) + +- Using the tarball: + +Get the tarball of the latest release, which can be found +`there `_, then untar it: + +.. code-block:: shell + + mkdir -p /opt/bastion + tar -C /opt/bastion -zxf v3.16.99-rc2.tar.gz + +The code supports being hosted somewhere else on the filesystem hierarchy, but this is discouraged as you might +need to adjust a lot of configuration files (notably sudoers.d, cron.d, init.d) that needs an absolute path. +You should end up with directories such as ``bin``, ``lib``, etc. directly under ``/opt/bastion``. + +.. _install-basic_install-packages: + +4. Install the needed packages +============================== + +For the supported Linux distros (see above), you can simply run: + +.. code-block:: shell + + /opt/bastion/bin/admin/packages-check.sh -i + +You can add other parameters to install optional packages, depending on your environment: + +- ``-s`` to install ``syslog-ng`` (advised, we have templates files for it) +- ``-d`` to install packages needed for developing the software (useless in production) + +You'll also need our version of ttyrec, `ovh-ttyrec `_. +To get and install the precompiled binary that will work for your OS and architecture, you can use this script: + +.. code-block:: shell + + /opt/bastion/bin/admin/install-ttyrec.sh -a + +This will detect your distro, then download and either install the ``.deb`` or ``.rpm`` package +for `ovh-ttyrec `_. If your distro doesn't handle those package types, +it'll fallback to installing precompiled static binaries. +Of course you can package it yourself and make it available to your own internal repositories instead of installing it this way. + +If you plan to use the PIV functionalities of The Bastion, +you'll also need to install the ``yubico-piv-checker`` `helper tool `_. + +You may also want to install ``the-bastion-mkhash-helper`` `tool `_ +if you want to be able to generate so-called type 8 and type 9 password hashes. + +.. code-block:: shell + + /opt/bastion/bin/admin/install-yubico-piv-checker.sh -a + /opt/bastion/bin/admin/install-mkhash-helper.sh -a + +.. _install-basic_encrypt-home: + +5. Encrypt /home +================ + +Strictly speaking, this step is optional, but if you skip it, know that all the SSH private keys and session +recordings will be stored unencrypted on the ``/home`` partition. +Of course, if partition encryption is already handled by the OS template you use, +or if the storage layer of your OS is encrypted by some other mean, you may skip this section. + +First, generate a secure password on your desk (but not too complicated so it can be typed +on a console over your hypervisor over a VDI over VPN over 4G in the dark at 3am on a Sunday) +and save it to a secure location: ``pwgen -s 10``. + +Then you can use the helper script to do this, it'll guide you through the process. +When prompted for a passphrase, enter the one chosen just before: + +.. code-block:: shell + + /opt/bastion/bin/admin/setup-encryption.sh + +If you get a cryptsetup error, you might need to add ``--type luks1`` to the ``cryptsetup luksFormat`` command +in the script. It can happen if your kernel doesn't have the necessary features enabled for LUKS2. + +.. warning:: + + Once you have setup encryption, **do not forget** to ensure that the keys backup script has encryption enabled, + otherwise the backups will be stored unencrypted in ``/root/backups``, + which would make your ``/home`` encryption moot. + This is not covered here because you can do it later, just don't forget it: + it's in the :doc:`advanced installation` section. + +.. _install-basic_setup: + +6. Setup bastion and system configuration +========================================= + +The following script will do that for you. There are several possibilities here. + +- If you're installing a new machine (nobody is using it as a bastion yet), then you can regenerate brand new + host keys and directly harden the ssh configuration without any side effect: + +.. code-block:: shell + + /opt/bastion/bin/admin/install --new-install + +- If you're upgrading an existing machine (from a previous version of this software), + and there are already some people using it as a bastion, then if you change the host keys, + they'll have to acknowledge the change when connecting, i.e. this is not transparent at all. + To avoid doing that and not touching either the ssh config or the host keys, use this: + +.. code-block:: shell + + /opt/bastion/bin/admin/install --upgrade + +If you used ``--upgrade``, then you are **warmly** advised to harden the configuration yourself, +using our templates as a basis. For example, if you're under Debian 11: + +.. code-block:: shell + + vimdiff /opt/bastion/etc/ssh/ssh_config.debian11 /etc/ssh/ssh_config + vimdiff /opt/bastion/etc/ssh/sshd_config.debian11 /etc/ssh/sshd_config + +There are other templates available in the same directory, for the other supported distros. + +- If you want to have a fine-grained control of what is managed by the installation script, + and what is managed by yourself (or any configuration automation system you may have), you can review all the fine-grained options: + +.. code-block:: shell + + /opt/bastion/bin/admin/install --help + +.. _install-basic_review-config: + +7. Review the configuration +=========================== + +Base configuration files have been copied, you should review the main configuration and modify it to your needs: + +.. code-block:: shell + + vim /etc/bastion/bastion.conf + +.. _install-basic_perl-check: + +8. Check that the code works on your machine +============================================ + +This script will verify that all required modules are installed: + +.. code-block:: shell + + /opt/bastion/bin/dev/perl-check.sh + +.. note:: + + If you're installing this instance to restore a backup, you may stop here and resume the + standard :doc:`/installation/restoring_from_backup` procedure. + +.. _install-basic_first-account: + +9. Manually create our first bastion account +============================================ + +Just launch this script, replacing *USERNAME* by the username you want to use: + +.. code-block:: shell + + /opt/bastion/bin/admin/setup-first-admin-account.sh USERNAME auto + +You'll just need to specify the public SSH key to add to this new account. +It'll be created as a bastion admin, and all the restricted commands will be granted. + +.. note:: + + This command will also give you a so-called *bastion alias*, this is the command you'll routinely use to + connect to the bastion, and to your infrastructures through it, replacing in effect your previous usage + of the `ssh` command. The alias name advertised on account creation is configurable in ``bastion.conf``, + and of course the users can rename it as they see fit, but it's advised to keep this command short, + as people will use it a lot. + +If you want to create other admin accounts, you can repeat the operation. +All the other accounts should be created by a bastion admin (or more precisely, +by somebody granted to the *accountCreate* command), using the bastion own commands. +But more about this in the section *Using the bastion*. + +You may head over to the **USAGE** section on the left menu, but please read the warning below first. + +.. warning:: + Note that even if your bastion should now be functional, proper setup for a production-level environment + is not done yet: for example, you don't have any backup system in place! Please ensure you follow the + :doc:`advanced installation` documentation and carely consider each step (by either completing it + or deciding that it's not mandatory for your use case), before considering your installation complete. + diff --git a/_sources/installation/docker.rst.txt b/_sources/installation/docker.rst.txt new file mode 100644 index 0000000..c424947 --- /dev/null +++ b/_sources/installation/docker.rst.txt @@ -0,0 +1,78 @@ +==================== +Sandbox using Docker +==================== + +This is a good way to test The Bastion within seconds, but :ref:`read the FAQ ` +if you're serious about using containerization in production. + +The sandbox image is available for the following architectures: ``linux/386``, ``linux/amd64``, ``linux/arm/v6``, +``linux/arm/v7``, ``linux/arm64``, ``linux/ppc64le``, ``linux/s390x``. + +- Let's run the docker image: + +.. code-block:: shell + + docker run -d -p 22 --name bastiontest ovhcom/the-bastion:sandbox + +- Or, if you prefer building the docker image yourself, you can: use the two commands below. + Of course, if you already typed the ``docker run`` command above, you can skip the following commands: + +.. code-block:: shell + + docker build -f docker/Dockerfile.debian10 -t bastion:debian10 . + docker run -d -p 22 --name bastiontest bastion:debian10 + +- Configure the first administrator account (get your public SSH key ready) + +.. code-block:: shell + + docker exec -it bastiontest /opt/bastion/bin/admin/setup-first-admin-account.sh poweruser auto + +- We're now up and running with the default configuration! + Let's setup a handy bastion alias, and test the ``info`` command: + +.. code-block:: shell + + PORT=$(docker port bastiontest | cut -d: -f2) + alias bastion="ssh poweruser@127.0.0.1 -tp $PORT -- " + bastion --osh info + +- It should greet you as being a bastion admin, which means you have access to all commands. + Let's enter interactive mode: + +.. code-block:: shell + + bastion -i + +- This is useful to call several ``--osh`` plugins in a row. Now we can ask for help to see all plugins: + +.. code-block:: shell + + $> help + +- If you have a remote machine you want to try to connect to through the bastion, fetch your egress key: + +.. code-block:: shell + + $> selfListEgressKeys + +- Copy this public key to the remote machine's ``authorized_keys`` under the ``.ssh/`` folder + of the account you want to connect to, then: + +.. code-block:: shell + + $> selfAddPersonalAccess --host --user --port-any + $> ssh @ + +- Note that you can connect directly without using interactive mode, with: + +.. code-block:: shell + + bastion @ + +That's it! You can head over to the **USAGE** section on the left menu for more information. +Be sure to check the help of the bastion with ``bastion --help``, +along with the help of each osh plugin with ``bastion --osh command --help``. + +Also don't forget to customize your ``bastion.conf`` file, +which can be found in ``/etc/bastion/bastion.conf`` (for Linux). diff --git a/_sources/installation/restoring_from_backup.rst.txt b/_sources/installation/restoring_from_backup.rst.txt new file mode 100644 index 0000000..6cd3bc6 --- /dev/null +++ b/_sources/installation/restoring_from_backup.rst.txt @@ -0,0 +1,149 @@ +===================== +Restoring from backup +===================== + +In this section, we'll detail how to restore a bastion's main data from a backup. + +This can be useful in two main cases: + +- When an account with high privileges has deleted or altered by mistake a great amount of accounts or groups, up + to a point where it's operationally easier to just restore the settings, accounts, groups and keys from the latest + available backup + +- When you are not in an :ref:`HA setup ` and your only + instance is down and can't be brought back up in a timely manner. + +Note that if you are in a HA setup and you need to add a new node (regardless of the fact that you're replacing +a failed node or not), you don't need to restore from backup: you can simply follow the HA setup procedure so +that your new node is synced with your main node. + +Prerequisites +============= + +First, you obviously must have a backup at hand, which should be the case if you followed the +:ref:`installadv_backup` section when you first installed the instance you want to restore. + +If the backup is encrypted with GPG (it should be), you must have access to the corresponding GPG private key and +its passphrase. + +You must ensure that the new server you're setting up has the same OS release than the one the backup file +comes from, as we'll overwrite the new server's accounts and groups files with the backed up versions. +This could cause adverse effects if the distro or release differ, although the restore script won't stop +you from doing so (it'll even help you adjust the discrepancies if needed, but again, this is strongly discouraged). + +Steps +===== + +Installation +------------ + +On the new server you want to deploy the backup to, you must first follow the standard :doc:`/installation/basic` +procedure, up to and including the *Check that the code works on your machine* step. + +Once done, you may proceed to the next steps below. + +GPG key and backup archive import +--------------------------------- + +On the server you've just installed, you'll need to import the private GPG key that was used to encrypt the backup, and +you'll also need to fetch the backup archive itself. It's a good practice to NOT decrypt the backup archive prior to +transferring it to the new server. This way, you're sure that the credentials and keys contained in the backup have +not been compromised. + +To import the GPG key, just run: + +.. code-block:: shell + :emphasize-lines: 1 + + gpg --import + +And paste the private GPG key corresponding to the backup so that it gets imported into root's keyring. + +Alternatively, you can put the private GPG key in a temporary file, and import it this way: + +.. code-block:: shell + :emphasize-lines: 1 + + gpg --import < /tmp/backupkey.asc + +You may now import the backup archive, which usually has a name matching the :file:`backup-YYYY-MM-DD.tar.gz.gpg` format. +You can use ``scp``, ``sftp`` or any other method to get this file onto the server, at any location you see fit. We'll use +:file:`/root` as location for the rest of this documentation, as this is guaranteed to only be readable by root, +hence not compromising the keys and credentials. + +Decrypt and extract accounts and groups +--------------------------------------- + +Now, you can decrypt the backup archive: + +.. code-block:: shell + :emphasize-lines: 1 + + gpg -d /root/backup-YYYY-MM-DD.tar.gz.gpg > /root/backup-decrypted.tar.gz + gpg: encrypted with 4096-bit RSA key, ID F50BFFC49143C821, created 2021-03-27 + "Bastion Administrators " + +You'll have to input the GPG private key passphrase when asked to. + +Then, check whether the archive seems okay: + +.. code-block:: shell + :emphasize-lines: 1 + + tar tvzf /root/backup-decrypted.tar.gz + +You should see a long list of files, most under the :file:`/home` hierarchy. + +We now need to extract the backed up :file:`/etc/passwd` and :file:`/etc/group` files, to ensure the new +instance we're setting up has its UIDs/GIDs synced with the system we're restoring: + +.. code-block:: shell + :emphasize-lines: 1 + + tar xvzf /root/backup-decrypted.tar.gz -C /root --strip-components=1 etc/passwd etc/group + etc/group + etc/passwd + +We now have the two original accounts and groups lists in :file:`/root`, and we can proceed to check +whether the UIDs and GIDs are in sync. + +Ensuring the UIDs/GIDs are in sync +---------------------------------- + +This procedure is the same than when setting up a slave instance bastion, +please follow the corresponding :ref:`step there` and come +back to this documentation when it's done. + +.. note:: + + The referenced step above asks you to reboot at the end, please ensure you've done it before + continuing with the rest of the procedure below. + +Restoring +--------- + +Now that we know the UIDs/GIDs are synced, we can proceed with the full restore: + +.. code-block:: shell + :emphasize-lines: 1 + + tar -C / --preserve-permissions --preserve-order --overwrite --acls --numeric-owner -xzvf /root/backup-decrypted.tar.gz + +.. note:: + + If you're getting errors such as 'Warning: Cannot acl_from_text: Invalid argument', please ensure that your + filesystem supports ACLs and is mounted with ACL support, otherwise ``tar`` can't restore ACLs from the backup. + +Back to production +------------------ + +As the configuration of the SSH daemon has also been restored, you might want to restart it so that it +picks up the new configuration: + +.. code-block:: shell + :emphasize-lines: 1 + + service ssh restart + +Once this is done, all the accounts that were present in the backup should be working. After ensuring this is the case, +you may put the server put back in production. diff --git a/_sources/installation/upgrading.rst.txt b/_sources/installation/upgrading.rst.txt new file mode 100644 index 0000000..22cd702 --- /dev/null +++ b/_sources/installation/upgrading.rst.txt @@ -0,0 +1,554 @@ +========= +Upgrading +========= + +General upgrade instructions +============================ + +- First, check below if there are specific upgrade instructions for your version. + +- When you're ready, update the code, if you're using ``git``, you can checkout the latest tag: + +.. code-block:: shell + + ( umask 0022 && cd /opt/bastion && git fetch && git checkout $(git tag | tail -1) ) + +- Run the install script in upgrade mode, so it can make adjustments to the system needed for the new version: + +.. code-block:: shell + + /opt/bastion/bin/admin/install --upgrade + +Note that if you're using an infrastructure automation tool such as Puppet, Ansible, Chef, +and don't want the update script to touch some files that you manage yourself, +you can use ``--managed-upgrade`` instead of ``--upgrade``. +See the ``--help`` for a more fine-grained upgrade path if needed. + +Version-specific upgrade instructions +===================================== + +v3.16.99-rc2 - 2024/09/17 +************************* + +This release drops support for Ubuntu 16.04 and CentOS 7. If you're still using these EOL OS releases (which is +obviously discouraged), proper functioning of The Bastion is no longer tested or guaranteed. +It also adds official support for Ubuntu 24.04 LTS and OpenSUSE Leap 15.6, these were already working but +are now part of the integration tests. + +This release adds support of wildcards (also called "shell-style globbing characters"), namely ``?`` and ``*``, +when using the ``--user`` option for plugins such as ``groupAddServer``, ``groupDelServer``, ``groupAddGuestAccess``, +``groupDelGuestAccess``, ``accountAddPersonalAccess``, ``accountDelPersonalAccess``, ``selfAddPersonalAccess``, +``selfDelPersonalAccess``. + +We also deprecate all the ``--sftp``, ``--scpdown``, ``--scpup`` options that are now replaced by a more generic +``--protocol`` option, which supports ``sftp``, ``scpdown ``, ``scpup`` and now also ``rsync`` as parameters. +The use of rsync is similar to sftp and scp, and is detailed here: :doc:`/plugins/open/rsync`. + +Last but not least, the ``sntrup761x25519-sha512@openssh.com`` KEX algorithm is now enabled by default on shipped +versions of ``sshd_config`` and ``ssh_config``. If you're upgrading, these files won't be touched, so if you want to +add support, you'll need to modify them manually by prepending ``sntrup761x25519-sha512@openssh.com`` to the +``KexAlgorithms`` line. Verify that the OpenSSH version shipped by your OS does support it (run ``ssh -Q kex``). + +v3.16.01 - 2024/04/17 +********************* + +No specific upgrade instructions. + +v3.16.00 - 2024/04/10 +********************* + +This version adds support for Secure Keys (FIDO2) for ingress authentication. It requires at least OpenSSH 8.2 +installed on the server hosting The Bastion, as support for FIDO2 was added in this version. +Of the currently supported OS versions, the following are known to have a recent-enough version: + +- Debian 11 +- Debian 12 +- Ubuntu 20.04 +- Ubuntu 22.04 +- OpenSUSE Leap 15.5 +- Rocky Linux 9 + +Note that if you are upgrading, you'll need to enable the new ingress algorithms in the ``/etc/bastion/bastion.conf`` +file, under the ``allowedIngressSshAlgorithms`` option. You may want to add ``ecdsa-sk`` and ``ed25519-sk`` to the list +if you want to support the FIDO2-backed versions of these two algorithms. +You may also refer to the distributed default configuration file in ``etc/bastion/bastion.conf.dist``, +which enables them by default. + +v3.15.00 - 2024/03/22 +********************* + +No specific upgrade instructions. + +v3.14.16 - 2024/02/20 +********************* + +No specific upgrade instructions. + +v3.14.15 - 2023/11/08 +********************* + +This release fixes the :doc:`/administration/security_advisories/cve_2023_45140` with severity 4.8 (CVSS V3). +Please refer to its page for impact and mitigation details. + +The changes introduced to fix this vulnerability imply that if you're using the ``scp`` or ``sftp`` plugins, +you'll need to update your wrappers using the new versions provided by this release. The old helpers will still +work, but only for remote hosts that don't require MFA. + +To get the new wrappers for your account on a given bastion, just call ``--osh scp`` or ``--osh sftp`` without +specifying any host, which will give you your script, and examples of use. +As you'll notice, the new scripts are no longer helpers (that were to be used through ``scp -S`` and +``sftp -S``), but wrappers, that will call ``scp`` and ``sftp`` themselves. + +As outlined above, the old helpers will still work for the foreseeable future, but as they're not able to +request MFA when this is configured for a remote host, they'll simply fail for such hosts on an updated +version of the bastion. + +If you have some accounts that use automated accesses through the bastion and use ``scp`` or ``sftp`` on +hosts that have JIT MFA configured through their group, you'll need to set these accounts as immune to JIT MFA, +which can be done through :doc:`/plugins/restricted/accountModify`'s ``--mfa-password-required bypass`` +and/or ``accountModify --mfa-totp-required bypass``, as has always been the case for classic SSH access. + +An HMAC shared secret is automatically generated when this release is deployed, this secret must be shared +by all the instances of the same cluster. Hence, you should start by deploying this release on the primary +node, which will generate the secret automatically during the standard upgrading procedure, so that this +node can push the shared-secret to the other nodes. The other nodes don't have to be upgraded beforehand, +they'll just not use the secret until they're upgraded to this version, and JIT MFA for ``scp`` and ``sftp`` +will not work through them until this is the case. + +Once the primary node is upgraded, you should ensure the new file containing the HMAC shared secret is part +of the synchronization list. If you did not customize your synchronization list, you can apply the new one +over the old one directly: + +.. code-block:: shell + :emphasize-lines: 1 + + cat /opt/bastion/etc/bastion/osh-sync-watcher.rsyncfilter.dist > /etc/bastion/osh-sync-watcher.rsyncfilter + +Then, you need to restart the synchronization daemon, so that it takes into consideration the new file +(containing the shared secret) to push to the other nodes. This is usually done this way: + +.. code-block:: shell + :emphasize-lines: 1 + + systemctl restart osh-sync-watcher + +You can verify on the other nodes that the ``/etc/bastion/mfa-token.conf`` file is now present. + +v3.14.00 - 2023/09/19 +********************* + +A new helper is required to support the so-called "type 8" and "type 9" password hash types, used on some +network devices. This helper is optional, and these hashes types will simply not be generated if the helper is +missing. The plugins concerned by this change are ``selfGeneratePassword``, ``selfListPasswords``, +``accountGeneratePassword``, ``accountListPasswords``, ``groupGeneratePassword``, ``groupListPasswords``. + +New installations will get this helper installed automatically. When upgrading, if you'd like to install +this helper, you'll need to install it by running the following command as ``root``: + +.. code-block:: shell + + /opt/bastion/bin/admin/install-mkhash-helper.sh -a + +This will detect your OS and either install a ``.deb`` file, an ``.rpm`` file, or a static binary. + +If you want to ensure that the helper has installed correctly, you can call it manually for testing purposes: + +.. code-block:: shell + :emphasize-lines: 1 + + echo test | the-bastion-mkhash-helper + {"Type8":"$8$EpvF1cVVzoEQFE$L3ZBWzfH9MTPo4WLX29Jd8LTM5sKlfEjtRZ//XMys2U","Type9":"$9$yRlXzt0T7WBs3E$YdKk8WMvLvAVcbglx.bMZoRlwBa6l5EhwLhBh1o0u4g","PasswordLen":4} + +If you're not generating passwords for use with network devices using type 8 or type 9 hash types, installation of this +helper is not required. + +v3.13.01 - 2023/08/22 +********************* + +No specific upgrade instructions. + +v3.13.00 - 2023/07/28 +********************* + +Plugins output is now recorded using ttyrec, as the connections are, instead of being stored in sqlite format +within the home folder of the account. This helps avoiding the sqlite databases growing too much in size when +accounts are using osh commands very intensively. + +v3.12.00 - 2023/06/27 +********************* + +Support for Debian 9 has been dropped. This doesn't mean that the code will suddenly stop working under this version, +but that tests no longer include this OS. Please consider upgrading to a more recent OS, as ensuring the underlying +OS is up to date and still supported is paramount to the security of The Bastion (or any other software). + +Support of Debian "Bookworm" 12 is now official, as this is now Debian stable. + +v3.11.02 - 2023/04/18 +********************* + +No specific upgrade instructions. + +v3.11.01 - 2023/03/27 +********************* + +No specific upgrade instructions. + +v3.11.00 - 2023/03/23 +********************* + +The upgrade path from the preceding version is straightforward, however there is a change +that you might want to be aware of before hitting the upgrade button: + +The previously implicitly assumed ``--port-any`` and ``--user-any`` options +to the ``(self|account)(Add|Del)PersonalAccess`` commands, when either ``--user`` or ``--port`` were omitted, +now require to be stated explicitly, to be consistent with the behaviour of ``group(Add|Del)Server``, +which always required it. Note that using this mechanism always emitted a deprecation warning, +since the first publicly released version, encouraging the explicit use of ``--user-any`` and/or ``--port-any`` +when this was desired. Now, omitting these options will simply return an error, +as this has always been the case with ``group(Add|Del)Server``. + +Example of previous behaviour:: + + $ bssh --osh selfAddPersonalAccess --host 127.0.0.5 --force + ╭──ac777d06bec9───────────────────────────────────────────the-bastion-3.10.00─── + │ ▶ adding personal access to a server on your account + ├─────────────────────────────────────────────────────────────────────────────── + │ ❗ You didn't specify --user or --user-any, defaulting to --user-any, this will no longer be implicit in future versions + │ ❗ You didn't specify --port or --port-any, defaulting to --port-any, this will no longer be implicit in future versions + │ Forcing add as asked, we didn't test the SSH connection, maybe it won't work! + │ Access to 127.0.0.5 was added to account jdoe + ╰─────────────────────────────────────────────────────── + +Example of new behaviour:: + + $ bssh --osh selfAddPersonalAccess --host 127.0.0.5 --force + ╭──ac777d06bec9───────────────────────────────────────────the-bastion-3.11.00─── + │ ▶ adding personal access to a server on your account + ├─────────────────────────────────────────────────────────────────────────────── + │ Add a personal server access on your account + │ + │ Usage: --osh selfAddPersonalAccess --host HOST [OPTIONS] + │ + │ --host IP|HOST|IP/MASK Server to add access to + │ --user USER Remote login to use, if you want to allow any login, use --user-any + │ --user-any Allow access with any remote login + │ --port PORT Remote SSH port to use, if you want to allow any port, use --port-any + │ --port-any Allow access to all remote ports + │ --scpup Allow SCP upload, you--bastion-->server (omit --user in this case) + │ --scpdown Allow SCP download, you<--bastion--server (omit --user in this case) + │ --sftp Allow usage of the SFTP subsystem, you<--bastion-->server (omit --user in this case) + │ --force Add the access without checking that the public SSH key is properly installed remotely + │ --force-key FINGERPRINT Only use the key with the specified fingerprint to connect to the server (cf selfListEgressKeys) + │ --force-password HASH Only use the password with the specified hash to connect to the server (cf selfListPasswords) + │ --ttl SECONDS|DURATION Specify a number of seconds (or a duration string, such as "1d7h8m") after which the access will automatically expire + │ --comment "'ANY TEXT'" Add a comment alongside this server. Quote it twice as shown if you're under a shell. + │ + │ ⛔ No user specified, if you want to add this server with any user, use --user-any + ╰─────────────────────────────────────────────────────── + +v3.10.00 - 2023/02/17 +********************* + +No specific upgrade instructions. + +v3.09.02 - 2022/11/15 +********************* + +No specific upgrade instructions. + +v3.09.01 - 2022/10/10 +********************* + +No specific upgrade instructions. + +v3.09.00 - 2022/09/21 +********************* + +This version has changes around the satellite system scripts that should be reviewed: + +- The ``osh-encrypt-rsync.pl`` script now also handles the account's access log and sql logs, + in addition to the ttyrec files. + A number of new options have been added to this script's config file, these options have sane defaults but you + might still want to review those, namely `encrypt_and_move_user_logs_delay_days `_ + and `encrypt_and_move_user_sqlites_delay_days `_. + +- As a result of the previous feature, the ``compress-old-logs.sh`` script has been retired. + +- A new script, ``osh-cleanup-guest-key-access.pl``, has been added. It is enabled by default, though it can + be disabled if you have a good reason to do so. Please refer to its `documentation `_ for more + information. + +- All scripts that are automatically run by cron and reside under the ``bin/cron`` subfolder now have their own + configuration file in ``/etc/bastion``, even for simple scripts that only have two configuration knobs: their + logging facility and whether they should be enabled or not. It is now recommended to use these configuration knobs + to disable the scripts you don't want to see running, instead of removing their corresponding file in the + ``/etc/cron.d`` folder, as any future update of the bastion would install them back. + +- The logging format has been standardized across these scripts, to ensure the newly included NRPE probes can detect + errors in the scripts more easily. By default the logs are going through syslog, using the ``local6`` facility, + which ends up in the ``/var/log/bastion/bastion-scripts.log`` folder if you're using our stock ``syslog-ng`` + configuration. The NRPE probes are available in the ``contrib/nrpe`` directory. + +Additionally, NRPE probes have been added, and should be used to monitor your bastion instances / clusters. +More information is available in the `NRPE probes readme file `_. + +Last but not least, CentOS 8 support has been dropped (whereas RockyLinux 8 will remain supported), +and Ubuntu 22.04 LTS support has been added. + +v3.08.01 - 2022/01/19 +********************* + +The upgrade path from the preceding version is straightforward, however you might want to know that there is +a new satellite script: ``osh-remove-empty-folders.sh``, run by cron and enabled by default, +whose job is to garbage-collect empty folders that may be piling up in busy users' homes, +under their ``ttyrec`` folder. + +You can find more information in `the documentation +`_, the script +is enabled by default because it can do no harm. + +v3.08.00 - 2022/01/04 +********************* + +This version replaces usage of GnuPG 1.x by GnuPG 2.x for the backup/encrypt/rsync satellite scripts, namely: + +- ``bin/cron/osh-backup-acl-keys.sh`` +- ``bin/cron/osh-encrypt-rsync.pl`` + +These are optionally used to help you backup your system, and encrypt/move out ttyrec files. +If you don't use these scripts and never configured them as seen in the :doc:`/installation/advanced` section, +then you have nothing to do. + +The script ``setup-gpg.sh`` will now create an Ed25519 key by default, instead of a 4K RSA key. +This type of key is usually seen as more secure (elliptic curve cryptography), and faster than RSA keys. +If you have already configured your system, then the above scripts will continue using the previously generated +RSA key, unless you generate a new key and reference it in the scripts configuration files. + +If you want to generate new Ed25519 keys instead of using your preexisting RSA keys, you may proceed +to the :ref:`Ed25519 section below `. + +Otherwise, on the first run, GnuPG 2.x should transparently import the 1.x keyring. +To verify that it worked correctly, you may want to try: + +.. code-block:: shell + + /opt/bastion/bin/cron/osh-encrypt-rsync.pl --config-test + +If you see *Config test passed*, and you're okay using your preexisting 4K RSA key, then you may stop here. + +If the test fails, and you know that before upgrading, this script worked correctly, then you might need to +manually import the GnuPG 1.x public keys: + +.. code-block:: shell + + gpg1 --armor --export | gpg --import + +Then, try again: + +.. code-block:: shell + + /opt/bastion/bin/cron/osh-encrypt-rsync.pl --config-test + +If you don't see any errors here, you're done. + +If you still see errors, then you might need to manually import the private key: + +.. code-block:: shell + + gpg1 --armor --export-secret-keys | gpg --import + +You may get asked for a password for the bastion secret key, which should be found in +``/etc/bastion/osh-encrypt-rsync.conf.d/50-gpg-bastion-key.conf`` if you previously used the script to generate it. + +A last config test should now work: + +.. code-block:: shell + + /opt/bastion/bin/cron/osh-encrypt-rsync.pl --config-test + +If you prefer to generate Ed25519 keys instead, then you can proceed to the next section. + +.. _upgrading_ed25519: + +Ed25519 +------- + +If you want to replace your RSA key by an Ed25519 one (which is optional), then you don't need to import the +GnuPG 1.x keys as outlined above but you may run instead: + +.. code-block:: shell + + /opt/bastion/bin/admin/setup-gpg.sh generate --overwrite + +Once the key has been generated, you may also want to generate a new admin key, by following this +:ref:`section ` of the Advanced Installation documentation. +Note that you'll need to use the ``--overwrite`` parameter when importing: + +.. code-block:: shell + + /opt/bastion/bin/admin/setup-gpg.sh import --overwrite + +Once done, a config test should work: + +.. code-block:: shell + + /opt/bastion/bin/cron/osh-encrypt-rsync.pl --config-test + +v3.07.00 - 2021/12/13 +********************* + +No specific upgrade instructions. + +v3.06.00 - 2021/10/15 +********************* + +The ``sshd_config`` templates have been modified to reflect the changes needed to use +the new ``--pubkey-auth-optional`` parameter of :doc:`/plugins/restricted/accountModify` +(`#237 `_). +If you want to use it, don't forget to review your ``sshd_config`` and modify it accordingly: +the templates can be found in ``etc/ssh/``. + +Note that misconfiguring `sshd` and `pam` together could at worst entirely disable sshd authentication. +If you have a custom configuration, different from the templates we provide, please double-check +that such corner case is not possible by design. +A good way to ensure this is to review the `pam` configuration and ensure that there is no execution +flow that pushes a `pam_success` value to the pam stack without requiring any form of authentication. + +v3.05.01 - 2021/09/22 +********************* + +In the configuration of the ``osh-backup-acl-keys`` script, a signing key can now be specified so that the backups +are signed by the bastion key in addition to being encrypted to the admin(s) key(s). +By default, the behaviour is the same as before: encrypt but don't sign. + +v3.05.00 - 2021/09/14 +********************* + +The maximum length of accounts is now 28 characters up from 18 characters previously. +If you have setup a HA cluster with several bastion instances synchronized together, note that accounts longer +than 18 characters will not be deemed as valid on not-yet upgraded instances of a cluster. + +v3.04.00 - 2021/07/02 +********************* + +The upgrade path from the preceding version is straightforward, however there are a few changes +that you might want to be aware of before hitting the upgrade button: + +- Some EOL OSes have been dropped: Debian 8, Ubuntu 14.04, OpenSUSE 15.0 and 15.1. + This means that while the software might still work, theses OSes are no longer part of the tests + and might break in any future upgrade. + +- The default logging level of the :doc:`/using/http_proxy` has been decreased. If you want to keep full requests + and responses logging, check the :doc:`log_request_response and log_request_response_max_size + ` configuration options. + +v3.03.01 - 2021/03/25 +********************* + +No specific upgrade instructions. + +v3.03.00 - 2021/02/22 +********************* + +No specific upgrade instructions. + +v3.02.00 - 2021/02/01 +********************* + +The upgrade path from the preceding version is straightforward, however there are a few changes +that you might want to be aware of before hitting the upgrade button: + +The main configuration file now supports proper booleans +-------------------------------------------------------- + +For a lot of configuration options, previously you would specify "1" to enable a feature, and "0" to disable it. +This has been changed to use proper *true* and *false* json values in :file:`/etc/bastion/bastion.conf`. +Of course, backward compatibility with "0" and "1" will always be kept, so no breakage is to be expected +for this version or future ones even if you keep your configuration untouched. + +Logs have been enhanced +----------------------- + +All connections and plugin executions emit two logs, an *open* and a *close* log. +We now add all the details of the connection to the *close* logs, those that were previously only available +in the corresponding *open* log. This way, it is no longer required to correlate both logs with their uniqid +to have all the data: the *close* log should suffice. +The *open* log is still there if for some reason the *close* log can't be emitted (kill -9, system crash, etc.), +or if the *open* and the *close* log are several hours, days or months appart. + +An additional field **duration** has been added to the *close* logs, +this represents the number of seconds (with millisecond precision) the connection lasted. + +Two new fields **globalsql** and **accountsql** have been added to the *open*-type logs. +These will contain either `ok` if we successfully logged to the corresponding log database, +`no` if it is disabled, or `error $aDetailedMessage` if we got an error trying to insert the row. +The *close*-type log also has the new **accountsql_close** field, but misses the **globalsql_close** field as +we never update the global database on this event. +On the *close* log, we can also have the value **missing**, indicating that we couldn't update the access log row +in the database, as the corresponding *open* log couldn't insert it. + +The **ttyrecsize** log field for the *close*-type logs has been removed, as it was never completely implemented, +and contains bogus data if ttyrec log rotation occurs. It has also been removed from the sqlite log databases. + +The *open* and *close* events are now pushed to our own log files, in addition to syslog, if logging to those files +is enabled (see :ref:`enableGlobalAccessLog` and :ref:`enableAccountAccessLog`), +previously the *close* events were only pushed to syslog. + +The :file:`/home/osh.log` file is no longer used for :ref:`enableGlobalAccessLog`, the global log +is instead written to :file:`/home/logkeeper/global-log-YYYYMM.log`. + +The global sql file, enabled with :ref:`enableGlobalSqlLog`, is now split by year-month instead of by year, +to :file:`/home/logkeeper/global-log-YYYYMM.sqlite`. + +v3.01.03 - 2020/12/15 +********************* + +No specific upgrade instructions. + +v3.01.02 - 2020/12/08 +********************* + +No specific upgrade instructions. + +v3.01.01 - 2020/12/04 +********************* + +No specific upgrade instructions. + +v3.01.00 - 2020/11/20 +********************* + +A new bastion.conf option was introduced: *interactiveModeByDefault*. If not present in your config file, +its value defaults to 1 (true), which changes the behavior of The Bastion when a user connects +without specifying any command. +When this happens, it'll now display the help then drop the user into interactive mode (if this mode is enabled), +instead of displaying the help and aborting with an error message. +Set it to 0 (false) if you want to keep the previous behavior. + +An SELinux module has been added in this version, to ensure TOTP MFA works correctly under systems where SELinux +is on enforcing mode. This module will be installed automatically whenever SELinux is detected on the system. +If you don't want to use this module, specify `--no-install-selinux-module` on your `/opt/bastion/bin/admin/install` +upgrade call (please refer to the generic upgrade instructions for more details). + +v3.00.02 - 2020/11/16 +********************* + +No specific upgrade instructions. + +v3.00.01 - 2020/11/06 +********************* + +If you previously installed ``ttyrec`` using the now deprecated ``build-and-install-ttyrec.sh`` script, +you might want to know that since this version, the script has been replaced by ``install-ttyrec.sh``, +which no longer builds in-place, but prefers downloading and installing prebuild ``rpm`` or ``deb`` packages. + +If you previously built and installed ``ttyrec`` manually, and want to use the new packages instead, +you might want to manually uninstall your previously built ttyrec program (remove the binaries that were installed +in ``/usr/local/bin``), and call ``install-ttyrec.sh -a`` to download and install the proper package instead. + +This is not mandatory and doesn't change anything from the software point of view. + +v3.00.00 - 2020/10/30 +********************* + +Initial public version, no specific upgrade instructions. diff --git a/_sources/plugins/admin/adminMaintenance.rst.txt b/_sources/plugins/admin/adminMaintenance.rst.txt new file mode 100644 index 0000000..e17c921 --- /dev/null +++ b/_sources/plugins/admin/adminMaintenance.rst.txt @@ -0,0 +1,28 @@ +================= +adminMaintenance +================= + +Manage the bastion maintenance mode +=================================== + + +.. admonition:: usage + :class: cmdusage + + --osh adminMaintenance <--lock [--message "'reason for maintenance'"]|--unlock> + +.. program:: adminMaintenance + + +.. option:: --lock + + Set maintenance mode: new logins will be disallowed + +.. option:: --unlock + + Unset maintenance mode: new logins are allowed and the bastion functions normally + +.. option:: --message MESSAGE + + Optionally set a maintenance reason, if you're in a shell, quote it twice. + diff --git a/_sources/plugins/admin/adminSudo.rst.txt b/_sources/plugins/admin/adminSudo.rst.txt new file mode 100644 index 0000000..4ef8674 --- /dev/null +++ b/_sources/plugins/admin/adminSudo.rst.txt @@ -0,0 +1,31 @@ +========== +adminSudo +========== + +Impersonate another user +======================== + + +.. admonition:: usage + :class: cmdusage + + --osh adminSudo -- --sudo-as ACCOUNT <--sudo-cmd PLUGIN -- [PLUGIN specific options...]> + +.. program:: adminSudo + + +.. option:: --sudo-as ACCOUNT + + Specify which bastion account we want to impersonate + +.. option:: --sudo-cmd PLUGIN + + --osh command we want to launch as the user (see --osh help) + + +Example:: + + --osh adminSudo -- --sudo-as user12 --sudo-cmd info -- --name somebodyelse + +Don't forget the double-double-dash as seen in the example above: one after the plugin name, +and another one to separate adminSudo options from the options of the plugin to be called. diff --git a/_sources/plugins/admin/index.rst.txt b/_sources/plugins/admin/index.rst.txt new file mode 100644 index 0000000..52632b5 --- /dev/null +++ b/_sources/plugins/admin/index.rst.txt @@ -0,0 +1,8 @@ +============== +admin plugins +============== + +.. toctree:: + + adminMaintenance + adminSudo diff --git a/_sources/plugins/group-aclkeeper/groupAddServer.rst.txt b/_sources/plugins/group-aclkeeper/groupAddServer.rst.txt new file mode 100644 index 0000000..ccd600b --- /dev/null +++ b/_sources/plugins/group-aclkeeper/groupAddServer.rst.txt @@ -0,0 +1,72 @@ +=============== +groupAddServer +=============== + +Add an IP or IP block to a group's servers list +=============================================== + + +.. admonition:: usage + :class: cmdusage + + --osh groupAddServer --group GROUP --host HOST --user USER|* --port PORT|* [OPTIONS] + +.. program:: groupAddServer + + +.. option:: --group GROUP + + Specify which group this machine should be added to + +.. option:: --host HOST|IP|NET/CIDR + + Host(s) to add access to, either a HOST which will be resolved to an IP immediately, + + or an IP, or a whole network using the NET/CIDR notation + --user USER|PATTERN|* Specify which remote user should be allowed to connect as. + Globbing characters '*' and '?' are supported, so you can specify a pattern + that will be matched against the actual remote user name. + To allow any user, use '--user *' (you might need to escape '*' from your shell) + --port PORT|* Remote port allowed to connect to + To allow any port, use '--port *' (you might need to escape '*' from your shell) +.. option:: --protocol PROTO + + Specify that a special protocol should be allowed for this HOST:PORT tuple, note that you + + must not specify --user in that case. However, for this protocol to be usable under a given + remote user, access to the USER@HOST:PORT tuple must also be allowed. + PROTO must be one of: + scpup allow SCP upload, you--bastion-->server + scpdown allow SCP download, you<--bastion--server + sftp allow usage of the SFTP subsystem, through the bastion + rsync allow usage of rsync, through the bastion +.. option:: --force + + Don't try the ssh connection, just add the host to the group blindly + +.. option:: --force-key FINGERPRINT + + Only use the key with the specified fingerprint to connect to the server (cf groupInfo) + +.. option:: --force-password HASH + + Only use the password with the specified hash to connect to the server (cf groupListPasswords) + +.. option:: --ttl SECONDS|DURATION + + Specify a number of seconds (or a duration string, such as "1d7h8m") after which the access will automatically expire + +.. option:: --comment "'ANY TEXT'" + + Add a comment alongside this server. Quote it twice as shown if you're under a shell. + + +Examples:: + + --osh groupAddServer --group grp1 --host 203.0.113.0/24 --user '*' --port '*' --force --ttl 1d12h --comment '"a whole network"' + --osh groupAddServer --group grp2 --host srv1.example.org --user data --port 22 + --osh groupAddServer --group grp2 --host srv1.example.org --user file --port 22 + +Example to allow using sftp to srv1.example.org using remote user 'data' or 'file', in addition to the above commands:: + + --osh groupAddServer --group grp2 --host srv1.example.org --port 22 --protocol sftp diff --git a/_sources/plugins/group-aclkeeper/groupDelServer.rst.txt b/_sources/plugins/group-aclkeeper/groupDelServer.rst.txt new file mode 100644 index 0000000..10ca738 --- /dev/null +++ b/_sources/plugins/group-aclkeeper/groupDelServer.rst.txt @@ -0,0 +1,50 @@ +=============== +groupDelServer +=============== + +Remove an IP or IP block from a group's server list +=================================================== + + +.. admonition:: usage + :class: cmdusage + + --osh groupDelServer --group GROUP --host HOST --user USER --port PORT [OPTIONS] + +.. program:: groupDelServer + + +.. option:: --group GROUP + + Specify which group this machine should be removed from + +.. option:: --host HOST|IP|NET/CIDR + + Host(s) to remove access from, either a HOST which will be resolved to an IP immediately, + + or an IP, or a whole network using the NET/CIDR notation + --user USER|PATTERN|* Specify which remote user was allowed to connect as. + Globbing characters '*' and '?' are supported, so you can specify a pattern + that will be matched against the actual remote user name. + If any user was allowed, use '--user *' (you might need to escape '*' from your shell) + --port PORT|* Remote port that was allowed to connect to + If any port was allowed, use '--port *' (you might need to escape '*' from your shell) +.. option:: --protocol PROTO + + Specify that a special protocol allowance should be removed from this HOST:PORT tuple, note that you + + must not specify --user in that case. + PROTO must be one of: + scpup allow SCP upload, you--bastion-->server + scpdown allow SCP download, you<--bastion--server + sftp allow usage of the SFTP subsystem, through the bastion + rsync allow usage of rsync, through the bastion + +This command adds, to an existing bastion account, access to a given server, using the +egress keys of the group. The list of eligible servers for a given group is given by ``groupListServers`` + +If you want to add member access to an account to all the present and future servers +of the group, using the group key, please use ``groupAddMember`` instead. + +If you want to add access to an account to a group server but using their personal bastion +key instead of the group key, please use ``accountAddPersonalAccess`` instead. diff --git a/_sources/plugins/group-aclkeeper/groupSetServers.rst.txt b/_sources/plugins/group-aclkeeper/groupSetServers.rst.txt new file mode 100644 index 0000000..d56c0f7 --- /dev/null +++ b/_sources/plugins/group-aclkeeper/groupSetServers.rst.txt @@ -0,0 +1,41 @@ +================ +groupSetServers +================ + +Replace a group's current ACL by a new list +=========================================== + + +.. admonition:: usage + :class: cmdusage + + --osh groupSetServers --group GROUP [OPTIONS] + +.. program:: groupSetServers + + +.. option:: --group GROUP + + Specify which group to modify the ACL of + +.. option:: --dry-run + + Don't actually modify the ACL, just report whether the input contains errors + +.. option:: --skip-errors + + Don't abort on STDIN parsing errors, just skip the non-parseable lines + + +The list of the assets to constitute the new ACL should then be given on ``STDIN``, +respecting the following format: ``[USER@]HOST[:PORT][ COMMENT]``, with ``USER`` and ``PORT`` being optional, +and ``HOST`` being either a hostname, an IP, or an IP block in CIDR notation. The ``COMMENT`` is also optional, +and may contain spaces. + +Example of valid lines to be fed through ``STDIN``:: + + server12.example.org + logs@server + 192.0.2.21 + host1.example.net:2222 host1 on secondary sshd with alternate port + root@192.0.2.0/24 production database cluster diff --git a/_sources/plugins/group-aclkeeper/index.rst.txt b/_sources/plugins/group-aclkeeper/index.rst.txt new file mode 100644 index 0000000..f95d8d1 --- /dev/null +++ b/_sources/plugins/group-aclkeeper/index.rst.txt @@ -0,0 +1,9 @@ +======================== +group-aclkeeper plugins +======================== + +.. toctree:: + + groupAddServer + groupDelServer + groupSetServers diff --git a/_sources/plugins/group-gatekeeper/groupAddGuestAccess.rst.txt b/_sources/plugins/group-gatekeeper/groupAddGuestAccess.rst.txt new file mode 100644 index 0000000..cf1e9f0 --- /dev/null +++ b/_sources/plugins/group-gatekeeper/groupAddGuestAccess.rst.txt @@ -0,0 +1,68 @@ +==================== +groupAddGuestAccess +==================== + +Add a specific group server access to an account +================================================ + + +.. admonition:: usage + :class: cmdusage + + --osh groupAddGuestAccess --group GROUP --account ACCOUNT [OPTIONS] + +.. program:: groupAddGuestAccess + + +.. option:: --account ACCOUNT + + Name of the other bastion account to add access to, they'll be given access to the GROUP key + +.. option:: --group GROUP + + Group to add the guest access to, note that this group should already have access + + to the USER/HOST/PORT tuple you'll specify with the options below. +.. option:: --host HOST|IP|NET/CIDR + + Host(s) to add access to, either a HOST which will be resolved to an IP immediately, + + or an IP, or a whole network using the NET/CIDR notation + --user USER|PATTERN|* Specify which remote user should be allowed to connect as. + Globbing characters '*' and '?' are supported, so you can specify a pattern + that will be matched against the actual remote user name. + To allow any user, use '--user *' (you might need to escape '*' from your shell) + --port PORT|* Remote port allowed to connect to + To allow any port, use '--port *' (you might need to escape '*' from your shell) +.. option:: --protocol PROTO + + Specify that a special protocol should be allowed for this HOST:PORT tuple, note that you + + must not specify --user in that case. However, for this protocol to be usable under a given + remote user, access to the USER@HOST:PORT tuple must also be allowed. + PROTO must be one of: + scpup allow SCP upload, you--bastion-->server + scpdown allow SCP download, you<--bastion--server + sftp allow usage of the SFTP subsystem, through the bastion + rsync allow usage of rsync, through the bastion +.. option:: --ttl SECONDS|DURATION + + Specify a number of seconds after which the access will automatically expire + +.. option:: --comment '"ANY TEXT"' + + Add a comment alongside this access. Quote it twice as shown if you're under a shell. + + If omitted, we'll use the closest preexisting group access' comment as seen in groupListServers + +This command adds, to an existing bastion account, access to the egress keys of a group, +but only to accessing one or several given servers, instead of all the servers of this group. + +If you want to add complete access to an account to all the present and future servers +of the group, using the group key, please use ``groupAddMember`` instead. + +If you want to add access to an account to a group server but using his personal bastion +key instead of the group key, please use ``accountAddPersonalAccess`` instead (his public key +must be on the remote server). + +This command is the opposite of ``groupDelGuestAccess``. diff --git a/_sources/plugins/group-gatekeeper/groupAddMember.rst.txt b/_sources/plugins/group-gatekeeper/groupAddMember.rst.txt new file mode 100644 index 0000000..074b53e --- /dev/null +++ b/_sources/plugins/group-gatekeeper/groupAddMember.rst.txt @@ -0,0 +1,29 @@ +=============== +groupAddMember +=============== + +Add an account to the member list +================================= + + +.. admonition:: usage + :class: cmdusage + + --osh groupAddMember --group GROUP --account ACCOUNT + +.. program:: groupAddMember + + +.. option:: --group GROUP + + which group to set ACCOUNT as a member of + +.. option:: --account ACCOUNT + + which account to set as a member of GROUP + + +The specified account will be able to access all present and future servers +pertaining to this group. +If you need to give a specific and/or temporary access instead, +see ``groupAddGuestAccess`` diff --git a/_sources/plugins/group-gatekeeper/groupDelGuestAccess.rst.txt b/_sources/plugins/group-gatekeeper/groupDelGuestAccess.rst.txt new file mode 100644 index 0000000..f9f373f --- /dev/null +++ b/_sources/plugins/group-gatekeeper/groupDelGuestAccess.rst.txt @@ -0,0 +1,57 @@ +==================== +groupDelGuestAccess +==================== + +Remove a specific group server access from an account +===================================================== + + +.. admonition:: usage + :class: cmdusage + + --osh groupDelGuestAccess --group GROUP --account ACCOUNT [OPTIONS] + +.. program:: groupDelGuestAccess + + +.. option:: --account ACCOUNT + + Bastion account remove the guest access from + +.. option:: --group GROUP + + Specify which group to remove the guest access to ACCOUNT from + +.. option:: --host HOST|IP|NET/CIDR + + Host(s) to remove access from, either a HOST which will be resolved to an IP immediately, + + or an IP, or a whole network using the NET/CIDR notation + --user USER|PATTERN|* Specify which remote user was allowed to connect as. + Globbing characters '*' and '?' are supported, so you can specify a pattern + that will be matched against the actual remote user name. + If any user was allowed, use '--user *' (you might need to escape '*' from your shell) + --port PORT|* Remote port that was allowed to connect to + If any user was allowed, use '--port *' (you might need to escape '*' from your shell) +.. option:: --protocol PROTO + + Specify that a special protocol was allowed for this HOST:PORT tuple, note that you + + must not specify --user in that case. However, for this protocol to be usable under a given + remote user, access to the USER@HOST:PORT tuple must also be allowed. + PROTO must be one of: + scpup allow SCP upload, you--bastion-->server + scpdown allow SCP download, you<--bastion--server + sftp allow usage of the SFTP subsystem, through the bastion + rsync allow usage of rsync, through the bastion + +This command removes, from an existing bastion account, access to a given server, using the +egress keys of the group. The list of such servers is given by ``groupListGuestAccesses`` + +If you want to remove member access from an account to all the present and future servers +of the group, using the group key, please use ``groupDelMember`` instead. + +If you want to remove access from an account from a group server but using their personal bastion +key instead of the group key, please use ``accountDelPersonalAccess`` instead. + +This command is the opposite of ``groupAddGuestAccess``. diff --git a/_sources/plugins/group-gatekeeper/groupDelMember.rst.txt b/_sources/plugins/group-gatekeeper/groupDelMember.rst.txt new file mode 100644 index 0000000..1e2ee84 --- /dev/null +++ b/_sources/plugins/group-gatekeeper/groupDelMember.rst.txt @@ -0,0 +1,29 @@ +=============== +groupDelMember +=============== + +Remove an account from the members list +======================================= + + +.. admonition:: usage + :class: cmdusage + + --osh groupDelMember --group GROUP --account ACCOUNT + +.. program:: groupDelMember + + +.. option:: --group GROUP + + which group to remove ACCOUNT as a member of + +.. option:: --account ACCOUNT + + which account to remove as a member of GROUP + + +The specified account will no longer be able to access all present and future servers +pertaining to this group. +Note that if this account also had specific guest accesses to this group, they may +still apply, see ``groupListGuestAccesses`` diff --git a/_sources/plugins/group-gatekeeper/groupListGuestAccesses.rst.txt b/_sources/plugins/group-gatekeeper/groupListGuestAccesses.rst.txt new file mode 100644 index 0000000..3354814 --- /dev/null +++ b/_sources/plugins/group-gatekeeper/groupListGuestAccesses.rst.txt @@ -0,0 +1,43 @@ +======================= +groupListGuestAccesses +======================= + +List the guest accesses to servers of a group specifically granted to an account +================================================================================ + + +.. admonition:: usage + :class: cmdusage + + --osh groupListGuestAccesses --group GROUP --account ACCOUNT + +.. program:: groupListGuestAccesses + + +.. option:: --group GROUP + + Look for accesses to servers of this GROUP + +.. option:: --account ACCOUNT + + Which account to check + +.. option:: --reverse-dns + + Attempt to resolve the reverse hostnames (SLOW!) + +.. option:: --include PATTERN + + Only include servers matching the given PATTERN (see below) + + This option can be used multiple times to refine results +.. option:: --exclude PATTERN + + Omit servers matching the given PATTERN (see below) + + This option can be used multiple times. + Note that --exclude takes precedence over --include + +**Note:** PATTERN supports the ``*`` and ``?`` wildcards. +If PATTERN is a simple string without wildcards, then names containing this string will be considered. +The matching is done on the text output of the command. diff --git a/_sources/plugins/group-gatekeeper/index.rst.txt b/_sources/plugins/group-gatekeeper/index.rst.txt new file mode 100644 index 0000000..0d3e4c4 --- /dev/null +++ b/_sources/plugins/group-gatekeeper/index.rst.txt @@ -0,0 +1,11 @@ +========================= +group-gatekeeper plugins +========================= + +.. toctree:: + + groupAddGuestAccess + groupAddMember + groupDelGuestAccess + groupDelMember + groupListGuestAccesses diff --git a/_sources/plugins/group-owner/groupAddAclkeeper.rst.txt b/_sources/plugins/group-owner/groupAddAclkeeper.rst.txt new file mode 100644 index 0000000..0f86dbb --- /dev/null +++ b/_sources/plugins/group-owner/groupAddAclkeeper.rst.txt @@ -0,0 +1,26 @@ +================== +groupAddAclkeeper +================== + +Add the group aclkeeper role to an account +========================================== + + +.. admonition:: usage + :class: cmdusage + + --osh groupAddAclkeeper --group GROUP --account ACCOUNT + +.. program:: groupAddAclkeeper + + +.. option:: --group GROUP + + which group to set ACCOUNT as an aclkeeper of + +.. option:: --account ACCOUNT + + which account to set as an aclkeeper of GROUP + + +The specified account will be able to manage the server list of this group diff --git a/_sources/plugins/group-owner/groupAddGatekeeper.rst.txt b/_sources/plugins/group-owner/groupAddGatekeeper.rst.txt new file mode 100644 index 0000000..1e2614f --- /dev/null +++ b/_sources/plugins/group-owner/groupAddGatekeeper.rst.txt @@ -0,0 +1,27 @@ +=================== +groupAddGatekeeper +=================== + +Add the group gatekeeper role to an account +=========================================== + + +.. admonition:: usage + :class: cmdusage + + --osh groupAddGatekeeper --group GROUP --account ACCOUNT + +.. program:: groupAddGatekeeper + + +.. option:: --group GROUP + + which group to set ACCOUNT as a gatekeeper of + +.. option:: --account ACCOUNT + + which account to set as a gatekeeper of GROUP + + +The specified account will be able to manage the members list of this group, +along with the guests list diff --git a/_sources/plugins/group-owner/groupAddOwner.rst.txt b/_sources/plugins/group-owner/groupAddOwner.rst.txt new file mode 100644 index 0000000..0dc14a6 --- /dev/null +++ b/_sources/plugins/group-owner/groupAddOwner.rst.txt @@ -0,0 +1,29 @@ +============== +groupAddOwner +============== + +Add the group owner role to an account +====================================== + + +.. admonition:: usage + :class: cmdusage + + --osh groupAddOwner --group GROUP --account ACCOUNT + +.. program:: groupAddOwner + + +.. option:: --group GROUP + + which group to set ACCOUNT as an owner of + +.. option:: --account ACCOUNT + + which account to set as an owner of GROUP + + +The specified account will be able to manage the owner, gatekeeper +and aclkeeper list of this group. In other words, this account will +have all possible rights to manage the group and delegate some or all +of the rights to other accounts diff --git a/_sources/plugins/group-owner/groupDelAclkeeper.rst.txt b/_sources/plugins/group-owner/groupDelAclkeeper.rst.txt new file mode 100644 index 0000000..e52f626 --- /dev/null +++ b/_sources/plugins/group-owner/groupDelAclkeeper.rst.txt @@ -0,0 +1,26 @@ +================== +groupDelAclkeeper +================== + +Remove the group aclkeeper role from an account +=============================================== + + +.. admonition:: usage + :class: cmdusage + + --osh groupDelAclkeeper --group GROUP --account ACCOUNT + +.. program:: groupDelAclkeeper + + +.. option:: --group GROUP + + which group to remove ACCOUNT as an aclkeeper of + +.. option:: --account ACCOUNT + + which account to remove as an aclkeeper of GROUP + + +The specified account will no longer be able to manage the server list of this group diff --git a/_sources/plugins/group-owner/groupDelEgressKey.rst.txt b/_sources/plugins/group-owner/groupDelEgressKey.rst.txt new file mode 100644 index 0000000..6b76062 --- /dev/null +++ b/_sources/plugins/group-owner/groupDelEgressKey.rst.txt @@ -0,0 +1,24 @@ +================== +groupDelEgressKey +================== + +Remove a bastion group egress key +================================= + + +.. admonition:: usage + :class: cmdusage + + --osh groupDelEgressKey <--group GROUP> <--id ID> + +.. program:: groupDelEgressKey + + +.. option:: --group GROUP + + Name of the group to delete the egress key from + +.. option:: --id ID + + Specify the key ID to delete, you can get it with groupInfo + diff --git a/_sources/plugins/group-owner/groupDelGatekeeper.rst.txt b/_sources/plugins/group-owner/groupDelGatekeeper.rst.txt new file mode 100644 index 0000000..1da1893 --- /dev/null +++ b/_sources/plugins/group-owner/groupDelGatekeeper.rst.txt @@ -0,0 +1,27 @@ +=================== +groupDelGatekeeper +=================== + +Remove the group gatekeeper role from an account +================================================ + + +.. admonition:: usage + :class: cmdusage + + --osh groupDelGatekeeper --group GROUP --account ACCOUNT + +.. program:: groupDelGatekeeper + + +.. option:: --group GROUP + + which group to remove ACCOUNT as a gatekeeper of + +.. option:: --account ACCOUNT + + which account to remove as a gatekeeper of GROUP + + +The specified account will no longer be able to manager the members nor +the guest list of this group diff --git a/_sources/plugins/group-owner/groupDelOwner.rst.txt b/_sources/plugins/group-owner/groupDelOwner.rst.txt new file mode 100644 index 0000000..9fabe2a --- /dev/null +++ b/_sources/plugins/group-owner/groupDelOwner.rst.txt @@ -0,0 +1,27 @@ +============== +groupDelOwner +============== + +Remove the group owner role from an account +=========================================== + + +.. admonition:: usage + :class: cmdusage + + --osh groupDelOwner --group GROUP --account ACCOUNT + +.. program:: groupDelOwner + + +.. option:: --group GROUP + + which group to set ACCOUNT as an owner of + +.. option:: --account ACCOUNT + + which account to set as an owner of GROUP + + +The specified account will no longer be able to manage the owner, +gatekeeper and aclkeeper lists of this group diff --git a/_sources/plugins/group-owner/groupDestroy.rst.txt b/_sources/plugins/group-owner/groupDestroy.rst.txt new file mode 100644 index 0000000..73de126 --- /dev/null +++ b/_sources/plugins/group-owner/groupDestroy.rst.txt @@ -0,0 +1,27 @@ +============= +groupDestroy +============= + +Delete a group +============== + + +.. admonition:: usage + :class: cmdusage + + --osh groupDestroy --group GROUP + +.. program:: groupDestroy + + +.. option:: --group GROUP + + Group name to delete + +.. option:: --no-confirm + + Skip group name confirmation, but blame yourself if you deleted the wrong group! + + +This command is able to delete any group you're an owner of. +Granted users to the sibling restricted command `groupDelete` can delete any group. diff --git a/_sources/plugins/group-owner/groupGenerateEgressKey.rst.txt b/_sources/plugins/group-owner/groupGenerateEgressKey.rst.txt new file mode 100644 index 0000000..2b803e4 --- /dev/null +++ b/_sources/plugins/group-owner/groupGenerateEgressKey.rst.txt @@ -0,0 +1,50 @@ +======================= +groupGenerateEgressKey +======================= + +Create a new public + private key pair for a group +================================================== + + +.. admonition:: usage + :class: cmdusage + + --osh groupGenerateEgressKey --group GROUP --algo ALGO --size SIZE [--encrypted] + +.. program:: groupGenerateEgressKey + + +.. option:: --group GROUP + + Group name to generate a new egress key for. + + +.. option:: --algo ALGO + + Specifies the algo of the key, either rsa, ecdsa or ed25519. + + +.. option:: --size SIZE + + Specifies the size of the key to be generated. + + For RSA, choose between 2048 and 8192 (4096 is good). + For ECDSA, choose either 256, 384 or 521. + For Ed25519, size is always 256. + +.. option:: --encrypted + + If specified, a passphrase will be prompted for the new key + + + +A quick overview of the different algorithms: + +.. code-block:: none + + Ed25519 : robustness[###] speed[###] + ECDSA : robustness[##.] speed[###] + RSA : robustness[#..] speed[#..] + +This table is meant as a quick cheat-sheet, you're warmly advised to do +your own research, as other constraints may apply to your environment. diff --git a/_sources/plugins/group-owner/groupGeneratePassword.rst.txt b/_sources/plugins/group-owner/groupGeneratePassword.rst.txt new file mode 100644 index 0000000..c01687f --- /dev/null +++ b/_sources/plugins/group-owner/groupGeneratePassword.rst.txt @@ -0,0 +1,40 @@ +====================== +groupGeneratePassword +====================== + +Generate a new egress password for the group +============================================ + + +.. admonition:: usage + :class: cmdusage + + --osh groupGeneratePassword --group GROUP [--size SIZE] --do-it + +.. program:: groupGeneratePassword + + +.. option:: --group GROUP + + Specify which group you want to generate a password for + +.. option:: --size SIZE + + Specify the number of characters of the password to generate + +.. option:: --do-it + + Required for the password to actually be generated, BEWARE: please read the note below + + +Generate a new egress password to be used for ssh or telnet + +NOTE: this is only needed for devices that don't support key-based SSH, +in most cases you should ignore this command completely, unless you +know that devices you need to access only support telnet or password-based SSH. + +BEWARE: once a new password is generated this way, it'll be set as the new +egress password to use right away for the group, for any access that requires it. +A fallback mechanism exists that will auto-try the previous password if this one +doesn't work, but please ensure that this new password is deployed on the remote +devices as soon as possible. diff --git a/_sources/plugins/group-owner/groupModify.rst.txt b/_sources/plugins/group-owner/groupModify.rst.txt new file mode 100644 index 0000000..d173d6f --- /dev/null +++ b/_sources/plugins/group-owner/groupModify.rst.txt @@ -0,0 +1,41 @@ +============ +groupModify +============ + +Modify the configuration of a group +=================================== + + +.. admonition:: usage + :class: cmdusage + + --osh groupModify --group GROUP [--mfa-required password|totp|any|none] [--guest-ttl-limit DURATION] + +.. program:: groupModify + + +.. option:: --group GROUP + + Name of the group to modify + +.. option:: --mfa-required password|totp|any|none + + Enforce UNIX password requirement, or TOTP requirement, or any MFA requirement, when connecting to a server of the group + + --idle-lock-timeout DURATION|0|-1 Overrides the global setting (`idleLockTimeout`), to the specified duration. If set to 0, disables `idleLockTimeout` for + this group. If set to -1, remove this group override and use the global setting instead. + --idle-kill-timeout DURATION|0|-1 Overrides the global setting (`idleKillTimeout`), to the specified duration. If set to 0, disables `idleKillTimeout` for + this group. If set to -1, remove this group override and use the global setting instead. +.. option:: --guest-ttl-limit DURATION + + This group will enforce TTL setting, on guest access creation, to be set, and not to a higher value than DURATION, + + set to zero to allow guest accesses creation without any TTL set (default) + +Note that `--idle-lock-timeout` and `--idle-kill-timeout` will NOT be applied for catch-all groups (having 0.0.0.0/0 in their server list). + +If a server is in exactly one group an account is a member of, then its values of `--idle-lock-timeout` and `--idle-kill-timeout`, if set, +will prevail over the global setting. The global setting can be seen with `--osh info`. + +Otherwise, the most restrictive setting (i.e. the one with the lower strictly positive duration) between +all the considered groups and the global setting, will be used. diff --git a/_sources/plugins/group-owner/groupTransmitOwnership.rst.txt b/_sources/plugins/group-owner/groupTransmitOwnership.rst.txt new file mode 100644 index 0000000..5f12575 --- /dev/null +++ b/_sources/plugins/group-owner/groupTransmitOwnership.rst.txt @@ -0,0 +1,27 @@ +======================= +groupTransmitOwnership +======================= + +Transmit your group ownership to somebody else +============================================== + + +.. admonition:: usage + :class: cmdusage + + --osh groupTransmitOwnership --group GROUP --account ACCOUNT + +.. program:: groupTransmitOwnership + + +.. option:: --group GROUP + + which group to set ACCOUNT as an owner of + +.. option:: --account ACCOUNT + + which account to set as an owner of GROUP + + +Note that this command has the same net effect than using ``groupAddOwner`` +to add ACCOUNT as an owner, then removing yourself with ``groupDelOwner`` diff --git a/_sources/plugins/group-owner/index.rst.txt b/_sources/plugins/group-owner/index.rst.txt new file mode 100644 index 0000000..387be69 --- /dev/null +++ b/_sources/plugins/group-owner/index.rst.txt @@ -0,0 +1,18 @@ +==================== +group-owner plugins +==================== + +.. toctree:: + + groupAddAclkeeper + groupAddGatekeeper + groupAddOwner + groupDelAclkeeper + groupDelEgressKey + groupDelGatekeeper + groupDelOwner + groupDestroy + groupGenerateEgressKey + groupGeneratePassword + groupModify + groupTransmitOwnership diff --git a/_sources/plugins/open/alive.rst.txt b/_sources/plugins/open/alive.rst.txt new file mode 100644 index 0000000..ee5c944 --- /dev/null +++ b/_sources/plugins/open/alive.rst.txt @@ -0,0 +1,23 @@ +====== +alive +====== + +Ping a host and exit as soon as it answers +========================================== + + +This command can be used to monitor a host that is expected to go back online soon. +Note that if you want to ssh to it afterwards, you can simply use the ``--wait`` main option. + +.. admonition:: usage + :class: cmdusage + + --osh alive [--host] HOSTNAME + +.. program:: alive + + +.. option:: --host HOSTNAME + + hostname or IP to ping + diff --git a/_sources/plugins/open/batch.rst.txt b/_sources/plugins/open/batch.rst.txt new file mode 100644 index 0000000..c69f485 --- /dev/null +++ b/_sources/plugins/open/batch.rst.txt @@ -0,0 +1,37 @@ +====== +batch +====== + +Run a batch of osh commands fed through STDIN +============================================= + + +.. admonition:: usage + :class: cmdusage + + --osh batch + +.. program:: batch + + +**Examples:** + +(replace ``bssh`` by your bastion alias) + +- run 3 simple commands in a oneliner: + +:: + + printf "%b\n%b\n%b" info selfListIngressKeys selfListEgressKeys | bssh --osh batch + +- run a lot of commands written out line by line in a file: + +:: + + bssh --osh batch < cmdlist.txt + +- add 3 users to a group: + +:: + + for i in user1 user2 user3; do echo "groupAddMember --account $i --group grp4"; done | bssh --osh batch diff --git a/_sources/plugins/open/clush.rst.txt b/_sources/plugins/open/clush.rst.txt new file mode 100644 index 0000000..9ec8919 --- /dev/null +++ b/_sources/plugins/open/clush.rst.txt @@ -0,0 +1,44 @@ +====== +clush +====== + +Launch a remote command on several machines sequentially (clush-like) +===================================================================== + + +.. admonition:: usage + :class: cmdusage + + --osh clush [OPTIONS] --command '"remote command"' + +.. program:: clush + + +.. option:: --list HOSTLIST + + Comma-separated list of the hosts (hostname or IP) to run the command on + +.. option:: --user USER + + Specify which remote user should we use to connect (default: BASTION_ACCOUNT) + +.. option:: --port PORT + + Specify which port to connect to (default: 22) + +.. option:: --step-by-step + + Pause before running the command on each host + +.. option:: --no-pause-on-failure + + Don't pause if the remote command failed (returned exit code != 0) + +.. option:: --no-confirm + + Skip confirmation of the host list and command + +.. option:: --command '"remote cmd"' + + Command to be run on the remote hosts. If you're in a shell, quote it twice as shown. + diff --git a/_sources/plugins/open/groupInfo.rst.txt b/_sources/plugins/open/groupInfo.rst.txt new file mode 100644 index 0000000..a3eb388 --- /dev/null +++ b/_sources/plugins/open/groupInfo.rst.txt @@ -0,0 +1,70 @@ +========== +groupInfo +========== + +Print some basic information about a group +========================================== + + +.. admonition:: usage + :class: cmdusage + + --osh groupInfo <--group GROUP|--all> [OPTIONS] + +.. program:: groupInfo + + +.. option:: --group GROUP + + Specify the group to display the info of + +.. option:: --all + + Dump info for all groups (auditors only), use with ``--json`` + + +.. option:: --with[out]-everything + + Include or exclude all below options, including future ones + +.. option:: --with[out]-keys + + Whether to include the group keys list (slow-ish, default: yes) + +Usage examples +============== + +Show info about a specific group:: + + --osh groupInfo --group mygroup2 + +Gather info about all groups, with no extra data except their keys:: + + --osh groupInfo --all --without-everything --with-keys --json + +Gather info about all groups, including all extra data (and possibly future options):: + + --osh groupInfo --all --with-everything --json + +Output example +============== + +.. code-block: none + + | Group mygroup's Owners are: user1 + | Group mygroup's GateKeepers (managing the members/guests list) are: user2 + | Group mygroup's ACLKeepers (managing the group servers list) are: user3 + | Group mygroup's Members (with access to ALL the group servers) are: user4 + | Group mygroup's Guests (with access to SOME of the group servers) are: user5 + | + | The public key of this group is: + | + | fingerprint: SHA256:r/PQS4wLdSWqjYsDca8ReKjhq0l9EX+zQgiUR5qKdlc (ED25519-256) [2018/04/16] + | keyline follows, please copy the *whole* line: + from="203.0.113.4/32,192.0.2.0/26" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILdD60bA3NgaOpRLgcACWfKcAMRQQRyFMppwp5GpHLTB mygroup@testbastion:1523886640 + +The first paragraph of the output lists the different roles along with the people having these roles. + +You can also see the public egress key of this group, i.e. the key that needs to be added to the remote servers' ``authorized_keys`` files, so that ``members`` of this group can access these servers. + +Note that if you want to see the list of servers pertaining to this group, you can use the command ``groupListServers``. diff --git a/_sources/plugins/open/groupList.rst.txt b/_sources/plugins/open/groupList.rst.txt new file mode 100644 index 0000000..02fe221 --- /dev/null +++ b/_sources/plugins/open/groupList.rst.txt @@ -0,0 +1,34 @@ +========== +groupList +========== + +List the groups available on this bastion +========================================= + + +.. admonition:: usage + :class: cmdusage + + --osh groupList [--all] [--exclude|--include PATTERN [--exclude|--include PATTERN ..]] + +.. program:: groupList + + +.. option:: --all + + List all groups, even those to which you don't have access + +.. option:: --include PATTERN + + Only list groups that match the given PATTERN (see below) + + This option can be used multiple times to refine results +.. option:: --exclude PATTERN + + Omit groups that match the given PATTERN string (see below) + + This option can be used multiple times. + Note that --exclude takes precedence over --include + +**Note:** PATTERN supports the ``*`` and ``?`` wildcards. +If PATTERN is a simple string without wildcards, then names containing this string will be considered. diff --git a/_sources/plugins/open/groupListPasswords.rst.txt b/_sources/plugins/open/groupListPasswords.rst.txt new file mode 100644 index 0000000..ed43641 --- /dev/null +++ b/_sources/plugins/open/groupListPasswords.rst.txt @@ -0,0 +1,22 @@ +=================== +groupListPasswords +=================== + +List the hashes and metadata of egress passwords of a group +=========================================================== + + +.. admonition:: usage + :class: cmdusage + + --osh groupListPasswords --group GROUP + +.. program:: groupListPasswords + + +.. option:: --group GROUP + + Show the data for this group + + +The passwords corresponding to these hashes are only needed for devices that don't support key-based SSH diff --git a/_sources/plugins/open/groupListServers.rst.txt b/_sources/plugins/open/groupListServers.rst.txt new file mode 100644 index 0000000..83b9318 --- /dev/null +++ b/_sources/plugins/open/groupListServers.rst.txt @@ -0,0 +1,39 @@ +================= +groupListServers +================= + +List the servers (IPs and IP blocks) pertaining to a group +========================================================== + + +.. admonition:: usage + :class: cmdusage + + --osh groupListServers --group GROUP [--reverse-dns] + +.. program:: groupListServers + + +.. option:: --group GROUP + + List the servers of this group + +.. option:: --reverse-dns + + Attempt to resolve the reverse hostnames (SLOW!) + +.. option:: --include PATTERN + + Only include servers matching the given PATTERN (see below) + + This option can be used multiple times to refine results +.. option:: --exclude PATTERN + + Omit servers matching the given PATTERN (see below) + + This option can be used multiple times. + Note that --exclude takes precedence over --include + +**Note:** PATTERN supports the ``*`` and ``?`` wildcards. +If PATTERN is a simple string without wildcards, then names containing this string will be considered. +The matching is done on the text output of the command. diff --git a/_sources/plugins/open/help.rst.txt b/_sources/plugins/open/help.rst.txt new file mode 100644 index 0000000..5ed31b8 --- /dev/null +++ b/_sources/plugins/open/help.rst.txt @@ -0,0 +1,31 @@ +===== +help +===== + +I'm So Meta, Even This Acronym +============================== + + +.. admonition:: usage + :class: cmdusage + + --osh help + +.. program:: help + +Displays help about the available plugins callable with ``--osh``. + +If you need help on a specific plugin, you can use ``--osh PLUGIN --help``, replacing ``PLUGIN`` with the actual plugin name. + +Note that if you want some help about the bastion (and not specifically about the plugins), you should use ``--help`` (without ``--osh``). + +Colors +====== + +You'll notice that plugins are highlighted in different colors, these indicate the access level needed to run the plugin. Note that plugins you don't have access to are simply omitted. + +- green (``open``): these plugins can be called by anybody +- blue (``restricted``): these plugins can only be called by users having the specific right to call them. This right is granted per plugin by the ``accountGrantCommand`` plugin +- orange (``group-gatekeeper`` and ``group-aclkeeper``): these plugins can either be called by group gatekeepers or group aclkeepers. For clarity, the same color has been used for both cases +- purple (``group-owner``): these plugins can only be called by group owners +- red (``admin``): these plugins can only be called by bastion admins diff --git a/_sources/plugins/open/index.rst.txt b/_sources/plugins/open/index.rst.txt new file mode 100644 index 0000000..4d57170 --- /dev/null +++ b/_sources/plugins/open/index.rst.txt @@ -0,0 +1,39 @@ +============= +open plugins +============= + +.. toctree:: + + alive + batch + clush + groupInfo + groupList + groupListPasswords + groupListServers + help + info + lock + mtr + nc + ping + rsync + scp + selfAddIngressKey + selfDelIngressKey + selfForgetHostKey + selfGenerateEgressKey + selfGeneratePassword + selfGenerateProxyPassword + selfListAccesses + selfListEgressKeys + selfListIngressKeys + selfListPasswords + selfListSessions + selfMFAResetPassword + selfMFAResetTOTP + selfMFASetupPassword + selfMFASetupTOTP + selfPlaySession + sftp + unlock diff --git a/_sources/plugins/open/info.rst.txt b/_sources/plugins/open/info.rst.txt new file mode 100644 index 0000000..e0b664e --- /dev/null +++ b/_sources/plugins/open/info.rst.txt @@ -0,0 +1,86 @@ +===== +info +===== + +Displays some information about this bastion instance +===================================================== + + +.. admonition:: usage + :class: cmdusage + + --osh info + +.. program:: info + +Output example +============== + +:: + + ~ You are user1 + ~ + ~ Your alias to connect to this bastion is: + ~ alias bastion='ssh user1@testbastion.example.org -p 22 -t -- ' + ~ Your alias to connect to this bastion with MOSH is: + ~ alias bastionm='mosh --ssh="ssh -p 22 -t" user1@testbastion.example.org -- ' + ~ + ~ Multi-Factor Authentication (MFA) on your account: + ~ - Additional password authentication is not required + ~ - Additional password authentication bypass is disabled + ~ - Additional password authentication is enabled and active + ~ - Additional TOTP authentication is not required + ~ - Additional TOTP authentication bypass is disabled + ~ - Additional TOTP authentication is disabled + ~ + ~ I am testbastion-a.example.org, aka bastion + ~ I have 42 registered accounts and 46 groups + ~ I am a MASTER, which means I accept modifications + ~ The networks I'm able to connect you to on the egress side are: all + ~ The networks that are explicitly forbidden on the egress side are: none + ~ My egress connection IP to remote servers is 192.0.2.45/32 + ~ ...don't forget to whitelist me in your firewalls! + ~ + ~ The following policy applies on this bastion: + ~ - The interactive mode (-i) is ENABLED + ~ - The support of mosh is ENABLED + ~ - Account expiration is DISABLED + ~ - Keyboard input idle time for session locking is DISABLED + ~ - Keyboard input idle time for session killing is DISABLED + ~ - The forced "from" prepend on ingress keys is DISABLED + ~ - The following algorithms are allowed for ingress SSH keys: rsa, ecdsa, ed25519 + ~ - The RSA key size for ingress SSH keys must be between 2048 and 8192 bits + ~ - The following algorithms are allowed for egress SSH keys: rsa, ecdsa, ed25519 + ~ - The RSA key size for egress SSH keys must be between 2048 and 8192 bits + ~ - The Multi-Factor Authentication (MFA) policy is ENABLED + ~ + ~ Here is your excuse for anything not working today: + ~ BOFH excuse #444: + ~ overflow error in /dev/null + + +Plugin configuration +==================== + +Options +------- + +.. option:: admin_show_system_info (optional, boolean) + + If enabled, bastion admins get more output regarding information of the + underlying OS. When omitted, this is enabled by default. + +.. option:: show_fortune (optional, boolean) + + If enabled, and if the ``fortune`` package is installed on your OS, + shows a fortune. When omitted, this is enabled by default. + +Example +------- + +Configuration, in JSON format, must be in :file:`/etc/bastion/plugin.info.conf`: + +.. code-block:: json + :emphasize-lines: 1 + + { "admin_show_system_info": false, "show_fortune": false } diff --git a/_sources/plugins/open/lock.rst.txt b/_sources/plugins/open/lock.rst.txt new file mode 100644 index 0000000..f0dfa81 --- /dev/null +++ b/_sources/plugins/open/lock.rst.txt @@ -0,0 +1,18 @@ +===== +lock +===== + +Manually lock all your current sessions +======================================= + + +.. admonition:: usage + :class: cmdusage + + --osh lock + +.. program:: lock + +This command will lock all your current sessions on this bastion instance. Note that this only applies to the bastion instance you're launching this command on, not on the whole bastion cluster (if you happen to have one). + +To undo this action, you can use ``--osh unlock`` on the same instance. diff --git a/_sources/plugins/open/mtr.rst.txt b/_sources/plugins/open/mtr.rst.txt new file mode 100644 index 0000000..9e2dccf --- /dev/null +++ b/_sources/plugins/open/mtr.rst.txt @@ -0,0 +1,20 @@ +==== +mtr +==== + +Runs the mtr tool to traceroute a host +====================================== + + +.. admonition:: usage + :class: cmdusage + + --osh mtr [--host] HOST [--report] + +.. program:: mtr + + +.. option:: --report + + Don't run mtr interactively, output a text report once done + diff --git a/_sources/plugins/open/nc.rst.txt b/_sources/plugins/open/nc.rst.txt new file mode 100644 index 0000000..9d6f6d6 --- /dev/null +++ b/_sources/plugins/open/nc.rst.txt @@ -0,0 +1,29 @@ +=== +nc +=== + +Check whether a remote TCP port is open +======================================= + + +.. admonition:: usage + :class: cmdusage + + --osh nc [--host] HOST [--port] PORT [-w TIMEOUT] + +.. program:: nc + + +.. option:: --host HOST + + Host or IP to attempt to connect to + +.. option:: --port PORT + + TCP port to attempt to connect to + +.. option:: -w SECONDS + + Timeout in seconds (default: 3) + +Note that this is not a full-featured ``netcat``, we just test whether a remote port is open. There is no way to exchange data using this command. diff --git a/_sources/plugins/open/ping.rst.txt b/_sources/plugins/open/ping.rst.txt new file mode 100644 index 0000000..a82b15c --- /dev/null +++ b/_sources/plugins/open/ping.rst.txt @@ -0,0 +1,36 @@ +===== +ping +===== + +Ping a remote host from the bastion +=================================== + + +.. admonition:: usage + :class: cmdusage + + --osh ping [--host HOST] [-c COUNT] [-s PKTSZ] [-t TTL] [-w TIMEOUT] + +.. program:: ping + + +.. option:: --host HOST + + Remote host to ping + +.. option:: -c COUNT + + Number of pings to send (default: infinite) + +.. option:: -s SIZE + + Specify the packet size to send + +.. option:: -t TTL + + TTL to set in the ICMP packet (default: OS dependent) + +.. option:: -w TIMEOUT + + Exit unconditionally after this amount of seconds (default & max: 86400) + diff --git a/_sources/plugins/open/rsync.rst.txt b/_sources/plugins/open/rsync.rst.txt new file mode 100644 index 0000000..4cdf17c --- /dev/null +++ b/_sources/plugins/open/rsync.rst.txt @@ -0,0 +1,35 @@ +====== +rsync +====== + +Transfer files from/to remote servers using rsync through the bastion +===================================================================== + +.. note:: + + This plugin should not be called manually, but passed as the --rsh option to rsync. + +Usage examples +-------------- + +To transfer all files from ``/srcdir`` to the ``remotehost``'s ``/dest/`` directory: + +.. code-block: none + + rsync -va --rsh "ssh -T BASTION_USER@BASTION_HOST -p BASTION_PORT -- --osh rsync --" /srcdir remoteuser@remotehost:/dest/ + +The ``-va`` options are just examples, you can use any option of ``rsync`` that you see fit. + +To transfer all remote files from ``/srcdir`` to the local ``/dest`` directory: + +.. code-block: none + + rsync -va --rsh "ssh -T BASTION_USER@BASTION_HOST -p BASTION_PORT -- --osh rsync --" remoteuser@remotehost:/srcdir /dest/ + +Please note that you need to be granted for uploading or downloading files +with ``rsync`` to/from the remote host, in addition to having the right to SSH to it. +For a group, the right should be added with ``--protocol rsync`` of the :doc:`/plugins/group-aclkeeper/groupAddServer` command. +For a personal access, the right should be added with ``--protocol rsync`` of the :doc:`/plugins/restricted/selfAddPersonalAccess` command. +:doc:`/plugins/open/selfListEgressKeys` + +You'll find more information and examples in :doc:`/using/sftp_scp_rsync`. diff --git a/_sources/plugins/open/scp.rst.txt b/_sources/plugins/open/scp.rst.txt new file mode 100644 index 0000000..14a4d80 --- /dev/null +++ b/_sources/plugins/open/scp.rst.txt @@ -0,0 +1,32 @@ +==== +scp +==== + +Transfer files from/to remote servers using scp through the bastion +=================================================================== + +.. note:: + + This plugin generates a valid helper script for you to use the bastion over scp, read below to learn how to use it. + +To be able to use ``scp`` over the bastion, you need to have a helper script that is specific +to your account on the bastion. This plugin's job is to generate it for you. +You can simply run it, and follow the guidelines. + +Once this is done, you'll be able to ``scp`` through the bastion by adding ``-S SCP_SCRIPT`` to your +regular ``scp`` command, where ``SCP_SCRIPT`` is the location of the script you've just generated. + +For example, to upload a file:: + + scp -S ~/scp_bastion localfile login@server:/dest/folder/ + +Or to recursively download a folder contents:: + + scp -S ~/scp_bastion -r login@server:/src/folder/ /tmp/ + +Please note that you need to be granted for uploading or downloading files +with scp to/from the remote host, in addition to having the right to SSH to it. +For a group, the right should be added with ``--scpup``/``--scpdown`` of the :doc:`/plugins/group-aclkeeper/groupAddServer` command. +For a personal access, the right should be added with ``--scpup``/``--scpdown`` of the :doc:`/plugins/restricted/selfAddPersonalAccess` command. + +You'll find more information and examples in :doc:`/using/sftp_scp_rsync`. diff --git a/_sources/plugins/open/selfAddIngressKey.rst.txt b/_sources/plugins/open/selfAddIngressKey.rst.txt new file mode 100644 index 0000000..80fa5a8 --- /dev/null +++ b/_sources/plugins/open/selfAddIngressKey.rst.txt @@ -0,0 +1,30 @@ +================== +selfAddIngressKey +================== + +Add a new ingress public key to your account +============================================ + + +.. admonition:: usage + :class: cmdusage + + --osh selfAddIngressKey [--public-key '"ssh key text"'] [--piv] + +.. program:: selfAddIngressKey + + +.. option:: --public-key KEY + + Your new ingress public SSH key to deposit on the bastion, use double-quoting if your're under a shell. + + If this option is not specified, you'll be prompted interactively for your public SSH key. Note that you + can also pass it through STDIN directly. If the policy of this bastion allows it, you may prefix the key + with a 'from="IP1,IP2,..."' snippet, a la authorized_keys. However the policy might force a configured + 'from' prefix that will override yours, or be used if you don't specify it yourself. +.. option:: --piv + + Add a public SSH key from a PIV-compatible hardware token, along with its attestation certificate and key + + certificate, both in PEM format. If you specified --public-key, then the attestation and key certificate are + expected on STDIN only, otherwise the public SSH key, the attestation and key certificate are expected on STDIN. diff --git a/_sources/plugins/open/selfDelIngressKey.rst.txt b/_sources/plugins/open/selfDelIngressKey.rst.txt new file mode 100644 index 0000000..433ed22 --- /dev/null +++ b/_sources/plugins/open/selfDelIngressKey.rst.txt @@ -0,0 +1,26 @@ +================== +selfDelIngressKey +================== + +Remove an ingress public key from your account +============================================== + + +.. admonition:: usage + :class: cmdusage + + --osh selfDelIngressKey [--id-to-delete|-l ID] [--fingerprint-to-delete|-f FP] + +.. program:: selfDelIngressKey + + +.. option:: -l, --id-to-delete ID + + Directly specify key id to delete (CAUTION!), you can get id with selfListIngressKeys + +.. option:: -f, --fingerprint-to-delete FP + + Directly specify the fingerprint of the key to delete (CAUTION!) + + +If none of these options are specified, you'll be prompted interactively. diff --git a/_sources/plugins/open/selfForgetHostKey.rst.txt b/_sources/plugins/open/selfForgetHostKey.rst.txt new file mode 100644 index 0000000..ca1f3b6 --- /dev/null +++ b/_sources/plugins/open/selfForgetHostKey.rst.txt @@ -0,0 +1,28 @@ +================== +selfForgetHostKey +================== + +Forget a known host key from your bastion account +================================================= + + +.. admonition:: usage + :class: cmdusage + + --osh selfForgetHostKey [--host HOST] [--port PORT] + +.. program:: selfForgetHostKey + + +.. option:: --host HOST + + Host to remove from the known_hosts file + +.. option:: --port PORT + + Port to look for in the known_hosts file (default: 22) + + +This command is useful to remove the man-in-the-middle warning when a key has changed, +however please verify that the host key change is legit before using this command. +The warning SSH gives is there for a reason. diff --git a/_sources/plugins/open/selfGenerateEgressKey.rst.txt b/_sources/plugins/open/selfGenerateEgressKey.rst.txt new file mode 100644 index 0000000..2c9c2ae --- /dev/null +++ b/_sources/plugins/open/selfGenerateEgressKey.rst.txt @@ -0,0 +1,45 @@ +====================== +selfGenerateEgressKey +====================== + +Create a new public + private key pair on your bastion account +============================================================== + + +.. admonition:: usage + :class: cmdusage + + --osh selfGenerateEgressKey --algo ALGO --size SIZE [--encrypted] + +.. program:: selfGenerateEgressKey + + +.. option:: --algo ALGO + + Specifies the algo of the key, either rsa, ecdsa or ed25519. + + +.. option:: --size SIZE + + Specifies the size of the key to be generated. + + For RSA, choose between 2048 and 8192 (4096 is good). + For ECDSA, choose either 256, 384 or 521. + For ED25519, size is always 256. + +.. option:: --encrypted + + if specified, a passphrase will be prompted for the new key + + + +A quick overview of the different algorithms: + +.. code-block:: none + + Ed25519 : robustness[###] speed[###] + ECDSA : robustness[##.] speed[###] + RSA : robustness[#..] speed[#..] + +This table is meant as a quick cheat-sheet, you're warmly advised to do +your own research, as other constraints may apply to your environment. diff --git a/_sources/plugins/open/selfGeneratePassword.rst.txt b/_sources/plugins/open/selfGeneratePassword.rst.txt new file mode 100644 index 0000000..4e37c33 --- /dev/null +++ b/_sources/plugins/open/selfGeneratePassword.rst.txt @@ -0,0 +1,36 @@ +===================== +selfGeneratePassword +===================== + +Generate a new egress password for your account +=============================================== + + +.. admonition:: usage + :class: cmdusage + + --osh selfGeneratePassword [--size SIZE] --do-it + +.. program:: selfGeneratePassword + + +.. option:: --size SIZE + + Specify the number of characters of the password to generate + +.. option:: --do-it + + Required for the password to actually be generated, BEWARE: please read the note below + + +This plugin generates a new egress password to be used for ssh or telnet + +NOTE: this is only needed for devices that don't support key-based SSH, +in most cases you should ignore this command completely, unless you +know that devices you need to access only support telnet or password-based SSH. + +BEWARE: once a new password is generated this way, it'll be set as the new +egress password to use right away for your account, for any access that requires it. +A fallback mechanism exists that will auto-try the previous password if this one +doesn't work, but please ensure that this new password is deployed on the remote +devices as soon as possible. diff --git a/_sources/plugins/open/selfGenerateProxyPassword.rst.txt b/_sources/plugins/open/selfGenerateProxyPassword.rst.txt new file mode 100644 index 0000000..27e7db2 --- /dev/null +++ b/_sources/plugins/open/selfGenerateProxyPassword.rst.txt @@ -0,0 +1,29 @@ +========================== +selfGenerateProxyPassword +========================== + +Generate a new ingress password to use the bastion HTTPS proxy +============================================================== + + +.. admonition:: usage + :class: cmdusage + + --osh selfGenerateProxyPassword --do-it + +.. program:: selfGenerateProxyPassword + + +.. option:: --do-it + + Required for the password to actually be generated, BEWARE: please read the note below + + +This plugin generates a new ingress password to use the bastion HTTPS proxy. + +NOTE: this is only needed for devices that only support HTTPS API and not ssh, +in most cases you should ignore this command completely, unless you +know that devices you need to access are using an HTTPS API. + +BEWARE: once a new password is generated this way, it'll be set as the new +HTTPS proxy ingress password to use right away for your account. diff --git a/_sources/plugins/open/selfListAccesses.rst.txt b/_sources/plugins/open/selfListAccesses.rst.txt new file mode 100644 index 0000000..af32b42 --- /dev/null +++ b/_sources/plugins/open/selfListAccesses.rst.txt @@ -0,0 +1,40 @@ +================= +selfListAccesses +================= + +Show the list of servers you have access to +=========================================== + + +.. admonition:: usage + :class: cmdusage + + --osh selfListAccesses [--hide-groups] [--reverse-dns] + +.. program:: selfListAccesses + + +.. option:: --hide-groups + + Don't show the machines you have access to through group rights. + + In other words, list only your personal accesses. +.. option:: --reverse-dns + + Attempt to resolve the reverse hostnames (SLOW!) + +.. option:: --include PATTERN + + Only include accesses matching the given PATTERN (see below) + + This option can be used multiple times to refine results +.. option:: --exclude PATTERN + + Omit accesses matching the given PATTERN (see below) + + This option can be used multiple times. + Note that --exclude takes precedence over --include + +**Note:** PATTERN supports the ``*`` and ``?`` wildcards. +If PATTERN is a simple string without wildcards, then names containing this string will be considered. +The matching is done on the text output of the command. diff --git a/_sources/plugins/open/selfListEgressKeys.rst.txt b/_sources/plugins/open/selfListEgressKeys.rst.txt new file mode 100644 index 0000000..9593330 --- /dev/null +++ b/_sources/plugins/open/selfListEgressKeys.rst.txt @@ -0,0 +1,20 @@ +=================== +selfListEgressKeys +=================== + +List the public egress keys of your account +=========================================== + + +.. admonition:: usage + :class: cmdusage + + --osh selfListEgressKeys + +.. program:: selfListEgressKeys + + +The keys listed are the public egress SSH keys tied to your account. +They can be used to gain access to another machine from this bastion, +by putting one of those keys in the remote machine's ``authorized_keys`` file, +and adding yourself access to this machine with ``selfAddPersonalAccess``. diff --git a/_sources/plugins/open/selfListIngressKeys.rst.txt b/_sources/plugins/open/selfListIngressKeys.rst.txt new file mode 100644 index 0000000..d8f3170 --- /dev/null +++ b/_sources/plugins/open/selfListIngressKeys.rst.txt @@ -0,0 +1,19 @@ +==================== +selfListIngressKeys +==================== + +List the public ingress keys of your account +============================================ + + +.. admonition:: usage + :class: cmdusage + + --osh selfListIngressKeys + +.. program:: selfListIngressKeys + + +The keys listed are the public ingress SSH keys tied to your account. +Their private counterpart should be detained only by you, and used +to authenticate yourself to this bastion. diff --git a/_sources/plugins/open/selfListPasswords.rst.txt b/_sources/plugins/open/selfListPasswords.rst.txt new file mode 100644 index 0000000..0d36c40 --- /dev/null +++ b/_sources/plugins/open/selfListPasswords.rst.txt @@ -0,0 +1,17 @@ +================== +selfListPasswords +================== + +List the hashes and metadata of the egress passwords associated to your account +=============================================================================== + + +.. admonition:: usage + :class: cmdusage + + --osh selfListPasswords + +.. program:: selfListPasswords + + +The passwords corresponding to these hashes are only needed for devices that don't support key-based SSH diff --git a/_sources/plugins/open/selfListSessions.rst.txt b/_sources/plugins/open/selfListSessions.rst.txt new file mode 100644 index 0000000..325fed2 --- /dev/null +++ b/_sources/plugins/open/selfListSessions.rst.txt @@ -0,0 +1,73 @@ +================= +selfListSessions +================= + +List the few past sessions of your account +========================================== + + +.. admonition:: usage + :class: cmdusage + + --osh selfListSessions [OPTIONS] + +.. program:: selfListSessions + + +.. option:: --detailed + + Display more information about each session + +.. option:: --limit LIMIT + + Limit to LIMIT results + +.. option:: --id ID + + Only sessions having this ID + +.. option:: --type TYPE + + Only sessions of specified type (ssh, osh, ...) + +.. option:: --allowed + + Only sessions that have been allowed by the bastion + +.. option:: --denied + + Only sessions that have been denied by the bastion + +.. option:: --after WHEN + + Only sessions that started after WHEN, + + WHEN can be a TIMESTAMP, or YYYY-MM-DD[@HH:MM:SS] +.. option:: --before WHEN + + Only sessions that started before WHEN, + + WHEN can be a TIMESTAMP, or YYYY-MM-DD[@HH:MM:SS] +.. option:: --host HOST + + Only sessions connecting to remote HOST + +.. option:: --to-port PORT + + Only sessions connecting to remote PORT + +.. option:: --user USER + + Only sessions connecting using remote USER + +.. option:: --via HOST + + Only sessions that connected through bastion IP HOST + +.. option:: --via-port PORT + + Only sessions that connected through bastion PORT + + +Note that only the sessions that happened on this precise bastion instance will be shown, +not the sessions from its possible cluster siblings. diff --git a/_sources/plugins/open/selfMFAResetPassword.rst.txt b/_sources/plugins/open/selfMFAResetPassword.rst.txt new file mode 100644 index 0000000..dacff4d --- /dev/null +++ b/_sources/plugins/open/selfMFAResetPassword.rst.txt @@ -0,0 +1,18 @@ +===================== +selfMFAResetPassword +===================== + +Remove the UNIX password of your account +======================================== + + +.. admonition:: usage + :class: cmdusage + + --osh selfMFAResetPassword + +.. program:: selfMFAResetPassword + + +Note that if your password is set, you'll be prompted for it. +Also note that this doesn't remove your UNIX password requirement, if set (see ``accountModify`` for this). diff --git a/_sources/plugins/open/selfMFAResetTOTP.rst.txt b/_sources/plugins/open/selfMFAResetTOTP.rst.txt new file mode 100644 index 0000000..dbeca49 --- /dev/null +++ b/_sources/plugins/open/selfMFAResetTOTP.rst.txt @@ -0,0 +1,18 @@ +================= +selfMFAResetTOTP +================= + +Remove the TOTP configuration of your account +============================================= + + +.. admonition:: usage + :class: cmdusage + + --osh selfMFAResetTOTP + +.. program:: selfMFAResetTOTP + + +Note that if your TOTP is set, you'll be prompted for it. +Also note that this doesn't remove your TOTP requirement, if set (see accountModify for this). diff --git a/_sources/plugins/open/selfMFASetupPassword.rst.txt b/_sources/plugins/open/selfMFASetupPassword.rst.txt new file mode 100644 index 0000000..d6d4d62 --- /dev/null +++ b/_sources/plugins/open/selfMFASetupPassword.rst.txt @@ -0,0 +1,20 @@ +===================== +selfMFASetupPassword +===================== + +Setup an additional credential (UNIX password) to access your account +===================================================================== + + +.. admonition:: usage + :class: cmdusage + + --osh selfMFASetupPassword [--yes] + +.. program:: selfMFASetupPassword + + +.. option:: --yes + + Don't ask for confirmation + diff --git a/_sources/plugins/open/selfMFASetupTOTP.rst.txt b/_sources/plugins/open/selfMFASetupTOTP.rst.txt new file mode 100644 index 0000000..9136f7c --- /dev/null +++ b/_sources/plugins/open/selfMFASetupTOTP.rst.txt @@ -0,0 +1,20 @@ +================= +selfMFASetupTOTP +================= + +Setup an additional credential (TOTP) to access your account +============================================================ + + +.. admonition:: usage + :class: cmdusage + + --osh selfMFASetupTOTP [--no-confirm] + +.. program:: selfMFASetupTOTP + + +.. option:: --no-confirm + + Bypass the confirmation step for TOTP enrollment phase + diff --git a/_sources/plugins/open/selfPlaySession.rst.txt b/_sources/plugins/open/selfPlaySession.rst.txt new file mode 100644 index 0000000..42500b3 --- /dev/null +++ b/_sources/plugins/open/selfPlaySession.rst.txt @@ -0,0 +1,20 @@ +================ +selfPlaySession +================ + +Replay the ttyrec of a past session +=================================== + + +.. admonition:: usage + :class: cmdusage + + --osh selfPlaySession --id ID + +.. program:: selfPlaySession + + +.. option:: --id ID + + ID of the session to replay, use ``selfListSessions`` to find it. + diff --git a/_sources/plugins/open/sftp.rst.txt b/_sources/plugins/open/sftp.rst.txt new file mode 100644 index 0000000..6711b83 --- /dev/null +++ b/_sources/plugins/open/sftp.rst.txt @@ -0,0 +1,35 @@ +===== +sftp +===== + +Transfer files from/to remote servers using sftp through the bastion +==================================================================== + +.. note:: + + This plugin generates a valid helper script for you to use the bastion over scp, read below to learn how to use it. + +To be able to use ``sftp`` over the bastion, you need to have a helper script that is specific +to your account on the bastion. This plugin's job is to generate it for you. +You can simply run it, and follow the guidelines. + +Once this is done, you'll be able to ``sftp`` through the bastion by adding ``-S SFTP_SCRIPT`` to your +regular ``sftp`` command, where ``SFTP_SCRIPT`` is the location of the script you've just generated. + +For example:: + + sftp -S ~/sftp_bastion login@server + +.. note:: + + If you're getting the 'subsystem request failed on channel 0' error, it usually means that + sftp is not enabled on the remote server, as this is not always enabled by default, depending + on the distro you're using. + +Please note that you need to be granted for uploading or downloading files +with SFTP to/from the remote host, in addition to having the right to SSH to it. +For a group, the right should be added with ``--sftp`` of the :doc:`/plugins/group-aclkeeper/groupAddServer` command. +For a personal access, the right should be added with ``--sftp`` of the :doc:`/plugins/restricted/selfAddPersonalAccess` command. +:doc:`/plugins/open/selfListEgressKeys` + +You'll find more information and examples in :doc:`/using/sftp_scp_rsync`. diff --git a/_sources/plugins/open/unlock.rst.txt b/_sources/plugins/open/unlock.rst.txt new file mode 100644 index 0000000..e2b4aa3 --- /dev/null +++ b/_sources/plugins/open/unlock.rst.txt @@ -0,0 +1,20 @@ +======= +unlock +======= + +Unlock all your current sessions +================================ + + +.. admonition:: usage + :class: cmdusage + + --osh unlock + +.. program:: unlock + + +This command will unlock all your current sessions on this bastion instance, +that were either locked for inactivity timeout or manually locked by you with ``lock``. +Note that this only applies to the bastion instance you're launching this +command on, not on the whole bastion cluster (if you happen to have one). diff --git a/_sources/plugins/restricted/accountAddPersonalAccess.rst.txt b/_sources/plugins/restricted/accountAddPersonalAccess.rst.txt new file mode 100644 index 0000000..bd9205c --- /dev/null +++ b/_sources/plugins/restricted/accountAddPersonalAccess.rst.txt @@ -0,0 +1,93 @@ +========================= +accountAddPersonalAccess +========================= + +Add a personal server access to an account +========================================== + + +.. admonition:: usage + :class: cmdusage + + --osh accountAddPersonalAccess --account ACCOUNT --host HOST --user USER --port PORT [OPTIONS] + +.. program:: accountAddPersonalAccess + + +.. option:: --account + + Bastion account to add the access to + +.. option:: --host HOST|IP|NET/CIDR + + Host(s) to add access to, either a HOST which will be resolved to an IP immediately, + + or an IP, or a whole network using the NET/CIDR notation + --user USER|PATTERN|* Specify which remote user should be allowed to connect as. + Globbing characters '*' and '?' are supported, so you can specify a pattern + that will be matched against the actual remote user name. + To allow any user, use '--user *' (you might need to escape '*' from your shell) + --port PORT|* Remote port allowed to connect to + To allow any port, use '--port *' (you might need to escape '*' from your shell) +.. option:: --protocol PROTO + + Specify that a special protocol should be allowed for this HOST:PORT tuple, note that you + + must not specify --user in that case. However, for this protocol to be usable under a given + remote user, access to the USER@HOST:PORT tuple must also be allowed. + PROTO must be one of: + scpup allow SCP upload, you--bastion-->server + scpdown allow SCP download, you<--bastion--server + sftp allow usage of the SFTP subsystem, through the bastion + rsync allow usage of rsync, through the bastion +.. option:: --force-key FINGERPRINT + + Only use the key with the specified fingerprint to connect to the server (cf accountListEgressKeys) + +.. option:: --force-password HASH + + Only use the password with the specified hash to connect to the server (cf accountListPasswords) + +.. option:: --ttl SECONDS|DURATION + + Specify a number of seconds (or a duration string, such as "1d7h8m") after which the access will automatically expire + +.. option:: --comment "'ANY TEXT'" + + Add a comment alongside this server. Quote it twice as shown if you're under a shell. + + +The access will work only if one of the account's personal egress public key has been copied to the remote server. +To get the list of an account's personal egress public keys, see ``accountListEgressKeyss`` and ``selfListEgressKeys``. + +Plugin configuration +==================== + +Options +------- + +.. option:: widest_v4_prefix (optional, integer, between 0 and 32) + + When specified, this limits the size of prefixes that can be added to an + ACL, e.g. 24 would not allow prefixes wider than /24 (such as /20 or + /16). + Note that this doesn't prevent users from adding thousands of ACLs to + cover a wide range of networks, but this helps ensuring ACLs such as + 0.0.0.0/0 can't be added in a single command. + +.. option:: self_remote_user_only (optional, boolean) + + When true, this only allows to add ACLs with the remote user being the + same than the account name, i.e. adding an access to a bastion account + named "johndoe" can only be done specifying this very account name as + the remote user name, with ``accountAddPersonalAccess --user johndoe``. + +Example +------- + +Configuration, in JSON format, must be in :file:`/etc/bastion/plugin.accountAddPersonalAccess.conf`: + +.. code-block:: json + :emphasize-lines: 1 + + { "widest_v4_prefix": 24, "self_remote_user_only": true } diff --git a/_sources/plugins/restricted/accountCreate.rst.txt b/_sources/plugins/restricted/accountCreate.rst.txt new file mode 100644 index 0000000..e86615d --- /dev/null +++ b/_sources/plugins/restricted/accountCreate.rst.txt @@ -0,0 +1,63 @@ +============== +accountCreate +============== + +Create a new bastion account +============================ + + +.. admonition:: usage + :class: cmdusage + + --osh accountCreate --account ACCOUNT <--uid UID|--uid-auto> [OPTIONS] + +.. program:: accountCreate + + +.. option:: --account NAME + + Account name to create, NAME must contain only valid UNIX account name characters + +.. option:: --uid UID + + Account system UID, also see --uid-auto + +.. option:: --uid-auto + + Auto-select an UID from the allowed range (the upper available one will be used) + +.. option:: --always-active + + This account's activation won't be challenged on connection, even if the bastion is globally + + configured to check for account activation +.. option:: --osh-only + + This account will only be able to use ``--osh`` commands, and can't connect anywhere through the bastion + +.. option:: --max-inactive-days DAYS + + Set account expiration policy, overriding the global bastion configuration 'accountMaxInactiveDays', + + setting this option to zero disables account expiration. +.. option:: --immutable-key + + Deny any subsequent modification of the account key (selfAddKey and selfDelKey are denied) + +.. option:: --comment '"STRING"' + + An optional comment when creating the account. Quote it twice as shown if you're under a shell. + +.. option:: --public-key '"KEY"' + + Account public SSH key to deposit on the bastion, if not present, + + you'll be prompted interactively for it. Quote it twice as shown if your're under a shell. +.. option:: --no-key + + Don't prompt for an SSH key, no ingress public key will be installed + +.. option:: --ttl SECONDS|DURATION + + Time after which the account will be deactivated (amount of seconds, or duration string such as "4d12h15m") + diff --git a/_sources/plugins/restricted/accountDelPersonalAccess.rst.txt b/_sources/plugins/restricted/accountDelPersonalAccess.rst.txt new file mode 100644 index 0000000..7fc5e63 --- /dev/null +++ b/_sources/plugins/restricted/accountDelPersonalAccess.rst.txt @@ -0,0 +1,41 @@ +========================= +accountDelPersonalAccess +========================= + +Remove a personal server access from an account +=============================================== + + +.. admonition:: usage + :class: cmdusage + + --osh accountDelPersonalAccess --account ACCOUNT --host HOST --user USER --port PORT [OPTIONS] + +.. program:: accountDelPersonalAccess + + +.. option:: --account + + Bastion account to remove access from + +.. option:: --host HOST|IP|NET/CIDR + + Host(s) to remove access from, either a HOST which will be resolved to an IP immediately, + + or an IP, or a whole network using the NET/CIDR notation + --user USER|PATTERN|* Specify which remote user was allowed to connect as. + Globbing characters '*' and '?' are supported, so you can specify a pattern + that will be matched against the actual remote user name. + If any user was allowed, use '--user *' (you might need to escape '*' from your shell) + --port PORT|* Remote port that was allowed to connect to + If any port was allowed, use '--port *' (you might need to escape '*' from your shell) +.. option:: --protocol PROTO + + Specify that a special protocol allowance should be removed from this HOST:PORT tuple, note that you + + must not specify --user in that case. + PROTO must be one of: + scpup allow SCP upload, you--bastion-->server + scpdown allow SCP download, you<--bastion--server + sftp allow usage of the SFTP subsystem, through the bastion + rsync allow usage of rsync, through the bastion diff --git a/_sources/plugins/restricted/accountDelete.rst.txt b/_sources/plugins/restricted/accountDelete.rst.txt new file mode 100644 index 0000000..dbacf0d --- /dev/null +++ b/_sources/plugins/restricted/accountDelete.rst.txt @@ -0,0 +1,24 @@ +============== +accountDelete +============== + +Delete an account from the bastion +================================== + + +.. admonition:: usage + :class: cmdusage + + --osh accountDelete --account ACCOUNT + +.. program:: accountDelete + + +.. option:: --account ACCOUNT + + Account name to delete + +.. option:: --no-confirm + + Don't ask for confirmation, and blame yourself if you deleted the wrong account + diff --git a/_sources/plugins/restricted/accountFreeze.rst.txt b/_sources/plugins/restricted/accountFreeze.rst.txt new file mode 100644 index 0000000..a4e4a46 --- /dev/null +++ b/_sources/plugins/restricted/accountFreeze.rst.txt @@ -0,0 +1,25 @@ +============== +accountFreeze +============== + +Freeze an account, to prevent it from connecting +================================================ + + +.. admonition:: usage + :class: cmdusage + + --osh accountFreeze --account ACCOUNT [--reason "'SOME REASON'"] + +.. program:: accountFreeze + + +.. option:: --account ACCOUNT + + Account to freeze + +.. option:: --reason "'SOME REASON'" + + Optional reason for the account to be frozen (will be displayed to the user), + + if you are in a shell (and not in interactive mode), quote it twice as shown. diff --git a/_sources/plugins/restricted/accountGeneratePassword.rst.txt b/_sources/plugins/restricted/accountGeneratePassword.rst.txt new file mode 100644 index 0000000..b4a897b --- /dev/null +++ b/_sources/plugins/restricted/accountGeneratePassword.rst.txt @@ -0,0 +1,40 @@ +======================== +accountGeneratePassword +======================== + +Generate a new egress password for an account +============================================= + + +.. admonition:: usage + :class: cmdusage + + --osh accountGeneratePassword --account ACCOUNT [--size SIZE] --do-it + +.. program:: accountGeneratePassword + + +.. option:: --account ACCOUNT + + Specify which account you want to generate a password for + +.. option:: --size SIZE + + Specify the number of characters of the password to generate + +.. option:: --do-it + + Required for the password to actually be generated, BEWARE: please read the note below + + +This plugin generates a new egress password to be used for ssh or telnet + +NOTE: this is only needed for devices that don't support key-based SSH, +in most cases you should ignore this command completely, unless you +know that devices you need to access only support telnet or password-based SSH. + +BEWARE: once a new password is generated this way, it'll be set as the new +egress password to use right away for the account, for any access that requires it. +A fallback mechanism exists that will auto-try the previous password if this one +doesn't work, but please ensure that this new password is deployed on the remote +devices as soon as possible. diff --git a/_sources/plugins/restricted/accountGrantCommand.rst.txt b/_sources/plugins/restricted/accountGrantCommand.rst.txt new file mode 100644 index 0000000..83895d3 --- /dev/null +++ b/_sources/plugins/restricted/accountGrantCommand.rst.txt @@ -0,0 +1,31 @@ +==================== +accountGrantCommand +==================== + +Grant access to a restricted command +==================================== + + +.. admonition:: usage + :class: cmdusage + + --osh accountGrantCommand --account ACCOUNT --command COMMAND + +.. program:: accountGrantCommand + + +.. option:: --account ACCOUNT + + Bastion account to work on + +.. option:: --command COMMAND + + The name of the OSH plugin to grant (omit to get the list) + + +Note that accountGrantCommand being a restricted command as any other, you can grant it to somebody else, +but then they'll be able to grant themselves or anybody else to this or any other restricted command. + +A specific command that can be granted is ``auditor``, it is not an osh plugin per-se, but activates +more verbose output for several other commands, suitable to audit rights or grants without needing +to be granted (e.g. to groups). diff --git a/_sources/plugins/restricted/accountInfo.rst.txt b/_sources/plugins/restricted/accountInfo.rst.txt new file mode 100644 index 0000000..3878530 --- /dev/null +++ b/_sources/plugins/restricted/accountInfo.rst.txt @@ -0,0 +1,112 @@ +============ +accountInfo +============ + +Display some information about an account +========================================= + + +.. admonition:: usage + :class: cmdusage + + --osh accountInfo <--account ACCOUNT|--all> [OPTIONS] + +.. program:: accountInfo + + +.. option:: --account ACCOUNT + + The account name to work on + +.. option:: --all + + Dump info for all accounts (auditors only), use with ``--json`` + + +.. option:: --with[out]-everything + + Include or exclude all below options, including future ones + +.. option:: --with[out]-groups + + Whether to include the groups the account has a role on (SLOW, default: no) + +.. option:: --with[out]-mfa-password-info + + Whether to include MFA password info of the account (SLOW, auditors only, default: no) + +.. option:: --with[out]-egress-keys + + Whether to include the account's egress keys (SLOW, auditors only, default: no) + +Usage examples +============== + +Show info about a specific account:: + + --osh accountInfo --account jdoe12 + +Gather info about all accounts, with no extra data except their egress keys:: + + --osh accountInfo --all --without-everything --with-egress-keys --json + +Gather info about all accounts, including all extra data (and possibly future options):: + + --osh accountInfo --all --with-everything --json + +Output example +============== + +:: + + │ user1 is a bastion admin + │ user1 is a bastion superowner + │ user1 is a bastion auditor + │ + │ user1 has access to the following restricted commands: + │ - accountCreate + │ - accountDelete + │ - groupCreate + │ - groupDelete + │ + │ This account is part of the following groups: + │ testgroup1 Owner GateKeeper ACLKeeper Member - + │ gatekeeper-grp2 Owner GateKeeper - - - + │ + │ This account is active + │ This account has no TTL set + │ This account is not frozen + │ This account has seen recent-enough activity to not be activity-expired + │ As a consequence, this account can connect to this bastion + │ + │ Last seen on Thu 2023-03-16 07:51:49 UTC (00:00:00 ago) + │ Created on Fri 2022-06-17 09:52:50 UTC (271d+21:58:59 ago) + │ Created by jdoe + │ Created using The Bastion v3.08.01 + │ + │ Account egress SSH config: + │ - (default) + │ + │ PIV-enforced policy for ingress keys on this account is enabled + │ + │ Account Multi-Factor Authentication status: + │ - Additional password authentication is not required for this account + │ - Additional password authentication bypass is disabled for this account + │ - Additional password authentication is enabled and active + │ - Additional TOTP authentication is not required for this account + │ - Additional TOTP authentication bypass is disabled for this account + │ - Additional TOTP authentication is disabled + │ - PAM authentication bypass is disabled + │ - Optional public key authentication is disabled + │ - MFA policy on personal accesses (using personal keys) on egress side is: password + │ + │ - Account is immune to idle counter-measures: no + │ - Maximum number of days of inactivity before account is disabled: (default) + │ + │ Account PAM UNIX password information (used for password MFA): + │ - Password is set + │ - Password was last changed on 2023-01-27 + │ - Password must be changed every 90 days at least + │ - A warning is displayed 75 days before expiration + │ - Account will not be disabled after password expiration + diff --git a/_sources/plugins/restricted/accountList.rst.txt b/_sources/plugins/restricted/accountList.rst.txt new file mode 100644 index 0000000..0ddeb08 --- /dev/null +++ b/_sources/plugins/restricted/accountList.rst.txt @@ -0,0 +1,50 @@ +============ +accountList +============ + +List the bastion accounts +========================= + + +.. admonition:: usage + :class: cmdusage + + --osh accountList [OPTIONS] + +.. program:: accountList + + +.. option:: --account ACCOUNT + + Only list the specified account. This is an easy way to check whether the account exists + +.. option:: --inactive-only + + Only list inactive accounts + +.. option:: --audit + + Show more verbose information (SLOW!), you need to be a bastion auditor + +.. option:: --no-password-info + + Don't gather password info in audit mode (makes --audit way faster) + +.. option:: --no-output + + Don't print human-readable output (faster, use with --json) + +.. option:: --include PATTERN + + Only show accounts whose name match the given PATTERN (see below) + + This option can be used multiple times to refine results +.. option:: --exclude PATTERN + + Omit accounts whose name match the given PATTERN (see below) + + This option can be used multiple times. + Note that --exclude takes precedence over --include + +**Note:** PATTERN supports the ``*`` and ``?`` wildcards. +If PATTERN is a simple string without wildcards, then names containing this string will be considered. diff --git a/_sources/plugins/restricted/accountListAccesses.rst.txt b/_sources/plugins/restricted/accountListAccesses.rst.txt new file mode 100644 index 0000000..68cf4ca --- /dev/null +++ b/_sources/plugins/restricted/accountListAccesses.rst.txt @@ -0,0 +1,44 @@ +==================== +accountListAccesses +==================== + +View the expanded access list of a given bastion account +======================================================== + + +.. admonition:: usage + :class: cmdusage + + --osh accountListAccesses --account ACCOUNT [--hide-groups] [--reverse-dns] + +.. program:: accountListAccesses + + +.. option:: --account ACCOUNT + + The account to work on + +.. option:: --hide-groups + + Don't show the machines the accouns has access to through group rights. + + In other words, list only the account's personal accesses. +.. option:: --reverse-dns + + Attempt to resolve the reverse hostnames (SLOW!) + +.. option:: --include PATTERN + + Only include accesses matching the given PATTERN (see below) + + This option can be used multiple times to refine results +.. option:: --exclude PATTERN + + Omit accesses matching the given PATTERN (see below) + + This option can be used multiple times. + Note that --exclude takes precedence over --include + +**Note:** PATTERN supports the ``*`` and ``?`` wildcards. +If PATTERN is a simple string without wildcards, then names containing this string will be considered. +The matching is done on the text output of the command. diff --git a/_sources/plugins/restricted/accountListEgressKeys.rst.txt b/_sources/plugins/restricted/accountListEgressKeys.rst.txt new file mode 100644 index 0000000..1827683 --- /dev/null +++ b/_sources/plugins/restricted/accountListEgressKeys.rst.txt @@ -0,0 +1,25 @@ +====================== +accountListEgressKeys +====================== + +List the public egress keys of an account +========================================= + + +.. admonition:: usage + :class: cmdusage + + --osh accountListEgressKeys --account ACCOUNT + +.. program:: accountListEgressKeys + + +.. option:: --account ACCOUNT + + Account to display the public egress keys of + + +The keys listed are the public egress SSH keys tied to this account. +They can be used to gain access to another machine from this bastion, +by putting one of those keys in the remote machine's ``authorized_keys`` file, +and adding this account access to this machine with ``accountAddPersonalAccess``. diff --git a/_sources/plugins/restricted/accountListIngressKeys.rst.txt b/_sources/plugins/restricted/accountListIngressKeys.rst.txt new file mode 100644 index 0000000..4b6902d --- /dev/null +++ b/_sources/plugins/restricted/accountListIngressKeys.rst.txt @@ -0,0 +1,24 @@ +======================= +accountListIngressKeys +======================= + +List the public ingress keys of an account +========================================== + + +.. admonition:: usage + :class: cmdusage + + --osh accountListIngressKeys --account ACCOUNT + +.. program:: accountListIngressKeys + + +.. option:: --account ACCOUNT + + Account to list the keys of + + +The keys listed are the public ingress SSH keys tied to this account. +Their private counterpart should be detained only by this account's user, +so that they can to authenticate themselves to this bastion. diff --git a/_sources/plugins/restricted/accountListPasswords.rst.txt b/_sources/plugins/restricted/accountListPasswords.rst.txt new file mode 100644 index 0000000..476b20e --- /dev/null +++ b/_sources/plugins/restricted/accountListPasswords.rst.txt @@ -0,0 +1,22 @@ +===================== +accountListPasswords +===================== + +List the hashes and metadata of the egress passwords associated to an account +============================================================================= + + +.. admonition:: usage + :class: cmdusage + + --osh accountListPasswords --account ACCOUNT + +.. program:: accountListPasswords + + +.. option:: --account ACCOUNT + + The account name to work on + + +The passwords corresponding to these hashes are only needed for devices that don't support key-based SSH diff --git a/_sources/plugins/restricted/accountMFAResetPassword.rst.txt b/_sources/plugins/restricted/accountMFAResetPassword.rst.txt new file mode 100644 index 0000000..81cd43f --- /dev/null +++ b/_sources/plugins/restricted/accountMFAResetPassword.rst.txt @@ -0,0 +1,22 @@ +======================== +accountMFAResetPassword +======================== + +Remove the UNIX password of an account +====================================== + + +.. admonition:: usage + :class: cmdusage + + --osh accountMFAResetPassword --account ACCOUNT + +.. program:: accountMFAResetPassword + + +.. option:: --account ACCOUNT + + Specify which account you want to remove the UNIX password of + + +Note that if doesn't remove the account UNIX password requirement, if set (see ``accountModify`` for this) diff --git a/_sources/plugins/restricted/accountMFAResetTOTP.rst.txt b/_sources/plugins/restricted/accountMFAResetTOTP.rst.txt new file mode 100644 index 0000000..cc56d22 --- /dev/null +++ b/_sources/plugins/restricted/accountMFAResetTOTP.rst.txt @@ -0,0 +1,22 @@ +==================== +accountMFAResetTOTP +==================== + +Remove the TOTP configuration of an account +=========================================== + + +.. admonition:: usage + :class: cmdusage + + --osh accountMFAResetTOTP --account ACCOUNT + +.. program:: accountMFAResetTOTP + + +.. option:: --account ACCOUNT + + Specify which account you want to remove the TOTP configuration of + + +Note that if doesn't remove the TOTP requirement, if set (see ``accountModify`` for this). diff --git a/_sources/plugins/restricted/accountModify.rst.txt b/_sources/plugins/restricted/accountModify.rst.txt new file mode 100644 index 0000000..d68db6c --- /dev/null +++ b/_sources/plugins/restricted/accountModify.rst.txt @@ -0,0 +1,87 @@ +============== +accountModify +============== + +Modify an account configuration +=============================== + + +.. admonition:: usage + :class: cmdusage + + --osh accountModify --account ACCOUNT [--option value [--option value [...]]] + +.. program:: accountModify + + +.. option:: --account ACCOUNT + + Bastion account to work on + +.. option:: --pam-auth-bypass yes|no + + Enable or disable PAM auth bypass for this account in addition to pubkey auth (default is 'no'), + + in that case sshd will not rely at all on PAM auth and /etc/pam.d/sshd configuration. This + does not change the behaviour of the code, just the PAM auth handled by SSH itself +.. option:: --mfa-password-required yes|no|bypass + + Enable or disable UNIX password requirement for this account in addition to pubkey auth (default is 'no'), + + this overrides the global bastion configuration 'accountMFAPolicy'. If 'bypass' is specified, + no password will ever be asked, even for groups or plugins explicitly requiring it +.. option:: --mfa-totp-required yes|no|bypass + + Enable or disable TOTP requirement for this account in addition to pubkey auth (default is 'no'), + + this overrides the global bastion configuration 'accountMFAPolicy'. If 'bypass' is specified, + no OTP will ever be asked, even for groups or plugins explicitly requiring it +.. option:: --egress-strict-host-key-checking POLICY + + Modify the egress SSH behavior of this account regarding ``StrictHostKeyChecking`` (see `man ssh_config`), + + POLICY can be 'yes', 'accept-new', 'no', 'ask', 'default' or 'bypass'. + 'bypass' means setting ``StrictHostKeyChecking=no`` and ``UserKnownHostsFile=/dev/null``, + which will permit egress connections in all cases, even when host keys change all the time on the same target. + This effectively suppress the host key checking entirely. Please don't enable this blindly. + 'default' will remove this account's ``StrictHostKeyChecking`` setting override. + All the other policies carry the same meaning that what is documented in `man ssh_config`. +.. option:: --egress-session-multiplexing POLICY + + Modify the egress SSH behavior of this account regarding ``ControlMaster`` and ``ControlPath``. POLICY can be: + + 'yes', setting ``ControlMaster`` to 'auto' and setting ``ControlPath`` properly for session sharing, + 'no', setting ``ControlMaster`` to 'no' and ``ControlPath`` to 'none', + 'default', removing this account ``ControlMaster`` and ``ControlPath`` overrides altogether. +.. option:: --personal-egress-mfa-required POLICY + + Enforce UNIX password requirement, or TOTP requirement, or any MFA requirement, when connecting to a server + + using the personal keys of the account, POLICY can be 'password', 'totp', 'any' or 'none' +.. option:: --always-active yes|no + + Set or unset the account as always active (i.e. disable the check of the 'active' status on this account) + +.. option:: --idle-ignore yes|no + + If enabled, this account is immune to the idleLockTimeout and idleKillTimeout bastion-wide policy + +.. option:: --max-inactive-days DAYS + + Set account expiration policy, overriding the global bastion configuration 'accountMaxInactiveDays'. + + Setting this option to zero disables account expiration. Setting this option to -1 removes this account + expiration policy, i.e. the global bastion setting will apply. +.. option:: --osh-only yes|no + + If enabled, this account can only use ``--osh`` commands, and can't connect anywhere through the bastion + +.. option:: --pubkey-auth-optional yes|no + + Make the public key optional on ingress for the account (default is 'no'). + + When enabled the public key part of the authentication becomes optional when a password and/or TOTP is defined, + allowing to login with just the password/TOTP. If no password/TOTP is defined then the public key is the only way to authenticate, + because some form of authentication is always required. + When disabled, the public key is always required. + Egress is not affected. diff --git a/_sources/plugins/restricted/accountPIV.rst.txt b/_sources/plugins/restricted/accountPIV.rst.txt new file mode 100644 index 0000000..5ac30c8 --- /dev/null +++ b/_sources/plugins/restricted/accountPIV.rst.txt @@ -0,0 +1,51 @@ +=========== +accountPIV +=========== + +Modify the PIV policy for the ingress keys of an account +======================================================== + + +.. admonition:: usage + :class: cmdusage + + --osh accountPIV --account ACCOUNT --policy + +.. program:: accountPIV + + +.. option:: --account ACCOUNT + + Bastion account to work on + +.. option:: --policy POLICY + + Changes the PIV policy of account. See below for a description of available policies. + +.. option:: --ttl SECONDS|DURATION + + For the ``grace`` policy, amount of time after which the account will automatically revert + + to its previous policy (amount of seconds, or duration string such as "4d12h15m"). + +Possible POLICY values: +----------------------- + +default + No specific policy is defined for this account, the default bastion policy applies (see the :ref:`ingressRequirePIV` global option). + +enforce + Only verified PIV keys can be added as ingress SSH keys for this account. Note that setting the policy to ``enforce`` also immediately + disables any non-PIV keys from the account's ingress keys. If no valid PIV key is found, this in effect disables all the keys of said + account, preventing connection. The disabled keys are still kept so that setting back the policy to ``default`` or ``never`` does restore + the non-PIV keys. + +never + Regardless of the global configuration of the bastion (see the :ref:`ingressRequirePIV` global option), this account will never be required + to use only PIV keys. This can be needed for a non-human account if PIV is enabled bastion-wide. + +grace + enables temporary deactivation of PIV enforcement on this account. This is only meaningful when the policy is already set to ``enforce`` + for this account, or if the global :ref:`ingressRequirePIV` option is set to true. This policy requires the use of the ``--ttl`` option to + specify how much time the policy will be relaxed for this account before going back to its previous policy automatically. This can be + useful when people forget their PIV-enabled hardware token and you don't want to send them back home. diff --git a/_sources/plugins/restricted/accountRevokeCommand.rst.txt b/_sources/plugins/restricted/accountRevokeCommand.rst.txt new file mode 100644 index 0000000..0b7fe12 --- /dev/null +++ b/_sources/plugins/restricted/accountRevokeCommand.rst.txt @@ -0,0 +1,24 @@ +===================== +accountRevokeCommand +===================== + +Revoke access to a restricted command +===================================== + + +.. admonition:: usage + :class: cmdusage + + --osh accountRevokeCommand --account ACCOUNT --command COMMAND + +.. program:: accountRevokeCommand + + +.. option:: --account ACCOUNT + + Bastion account to work on + +.. option:: --command COMMAND + + The name of the OSH plugin to revoke access to (omit to get the list) + diff --git a/_sources/plugins/restricted/accountUnexpire.rst.txt b/_sources/plugins/restricted/accountUnexpire.rst.txt new file mode 100644 index 0000000..4b0ea70 --- /dev/null +++ b/_sources/plugins/restricted/accountUnexpire.rst.txt @@ -0,0 +1,23 @@ +================ +accountUnexpire +================ + +Unexpire an inactivity-expired account +====================================== + + +.. admonition:: usage + :class: cmdusage + + --osh accountUnexpire --account ACCOUNT + +.. program:: accountUnexpire + + +.. option:: --account ACCOUNT + + Account to work on + + +When the bastion is configured to expire accounts that haven't been seen in a while, +this command can be used to activate them back. diff --git a/_sources/plugins/restricted/accountUnfreeze.rst.txt b/_sources/plugins/restricted/accountUnfreeze.rst.txt new file mode 100644 index 0000000..82f6a99 --- /dev/null +++ b/_sources/plugins/restricted/accountUnfreeze.rst.txt @@ -0,0 +1,20 @@ +================ +accountUnfreeze +================ + +Unfreeze a frozen account +========================= + + +.. admonition:: usage + :class: cmdusage + + --osh accountUnfreeze --account ACCOUNT + +.. program:: accountUnfreeze + + +.. option:: --account ACCOUNT + + Account to unfreeze + diff --git a/_sources/plugins/restricted/accountUnlock.rst.txt b/_sources/plugins/restricted/accountUnlock.rst.txt new file mode 100644 index 0000000..0f25efe --- /dev/null +++ b/_sources/plugins/restricted/accountUnlock.rst.txt @@ -0,0 +1,20 @@ +============== +accountUnlock +============== + +Unlock an account locked by pam_tally, pam_tally2 or pam_faillock +================================================================= + + +.. admonition:: usage + :class: cmdusage + + --osh accountUnlock --account ACCOUNT + +.. program:: accountUnlock + + +.. option:: --account ACCOUNT + + Account to work on + diff --git a/_sources/plugins/restricted/groupCreate.rst.txt b/_sources/plugins/restricted/groupCreate.rst.txt new file mode 100644 index 0000000..f7625d0 --- /dev/null +++ b/_sources/plugins/restricted/groupCreate.rst.txt @@ -0,0 +1,60 @@ +============ +groupCreate +============ + +Create a group +============== + + +.. admonition:: usage + :class: cmdusage + + --osh groupCreate --group GROUP --owner ACCOUNT <--algo ALGO --size SIZE [--encrypted]|--no-key> + +.. program:: groupCreate + + +.. option:: --group + + Group name to create + + +.. option:: --owner + + Preexisting bastion account to assign as owner (can be you) + + +.. option:: --encrypted + + Add a passphrase to the key. Beware that you'll have to enter it for each use. + + Do NOT add the passphrase after this option, you'll be prompted interactively for it. + +.. option:: --algo + + Specifies the algo of the key, either rsa, ecdsa or ed25519. + +.. option:: --size + + Specifies the size of the key to be generated. + + For RSA, choose between 2048 and 8192 (4096 is good). + For ECDSA, choose either 256, 384 or 521. + For ED25519, size is always 256. + +.. option:: --no-key + + Don't generate an egress SSH key at all for this group + + + +A quick overview of the different algorithms: + +.. code-block:: none + + Ed25519 : robustness[###] speed[###] + ECDSA : robustness[##.] speed[###] + RSA : robustness[#..] speed[#..] + +This table is meant as a quick cheat-sheet, you're warmly advised to do +your own research, as other constraints may apply to your environment. diff --git a/_sources/plugins/restricted/groupDelete.rst.txt b/_sources/plugins/restricted/groupDelete.rst.txt new file mode 100644 index 0000000..61a0ead --- /dev/null +++ b/_sources/plugins/restricted/groupDelete.rst.txt @@ -0,0 +1,27 @@ +============ +groupDelete +============ + +Delete a group +============== + + +.. admonition:: usage + :class: cmdusage + + --osh groupDelete --group GROUP + +.. program:: groupDelete + + +.. option:: --group GROUP + + Group name to delete + +.. option:: --no-confirm + + Skip group name confirmation, but blame yourself if you deleted the wrong group! + + +This restricted command is able to delete any group. Group owners can however delete +their own groups using the sibling `groupDestroy` command. diff --git a/_sources/plugins/restricted/index.rst.txt b/_sources/plugins/restricted/index.rst.txt new file mode 100644 index 0000000..05c0917 --- /dev/null +++ b/_sources/plugins/restricted/index.rst.txt @@ -0,0 +1,37 @@ +=================== +restricted plugins +=================== + +.. toctree:: + + accountAddPersonalAccess + accountCreate + accountDelPersonalAccess + accountDelete + accountFreeze + accountGeneratePassword + accountGrantCommand + accountInfo + accountList + accountListAccesses + accountListEgressKeys + accountListIngressKeys + accountListPasswords + accountMFAResetPassword + accountMFAResetTOTP + accountModify + accountPIV + accountRevokeCommand + accountUnexpire + accountUnfreeze + accountUnlock + groupCreate + groupDelete + realmCreate + realmDelete + realmInfo + realmList + rootListIngressKeys + selfAddPersonalAccess + selfDelPersonalAccess + whoHasAccessTo diff --git a/_sources/plugins/restricted/realmCreate.rst.txt b/_sources/plugins/restricted/realmCreate.rst.txt new file mode 100644 index 0000000..5294e25 --- /dev/null +++ b/_sources/plugins/restricted/realmCreate.rst.txt @@ -0,0 +1,34 @@ +============ +realmCreate +============ + +Declare and create a new trusted realm +====================================== + + +.. admonition:: usage + :class: cmdusage + + --osh realmCreate --realm REALM --from IP1,IP2 [OPTIONS] + +.. program:: realmCreate + + +.. option:: --realm REALM + + Realm name to create + +.. option:: --comment STRING + + An optional comment when creating the realm. Double-quote if you're under a shell. + +.. option:: --from + + IP1,IP2 Comma-separated list of outgoing IPs used by the realm we're declaring (i.e. IPs used by the bastion(s) on the other side) + + the expected format is the one used by the from="" directive on SSH keys (IP and prefixes are supported) +.. option:: --public-key KEY + + Public SSH key to deposit on the bastion to access this realm. If not present, + + you'll be prompted interactively for it. Use double-quoting if your're under a shell. diff --git a/_sources/plugins/restricted/realmDelete.rst.txt b/_sources/plugins/restricted/realmDelete.rst.txt new file mode 100644 index 0000000..4bab964 --- /dev/null +++ b/_sources/plugins/restricted/realmDelete.rst.txt @@ -0,0 +1,20 @@ +============ +realmDelete +============ + +Delete a bastion realm +====================== + + +.. admonition:: usage + :class: cmdusage + + --osh realmDelete --realm REALM + +.. program:: realmDelete + + +.. option:: --realm REALM + + Name of the realm to delete + diff --git a/_sources/plugins/restricted/realmInfo.rst.txt b/_sources/plugins/restricted/realmInfo.rst.txt new file mode 100644 index 0000000..ff1bced --- /dev/null +++ b/_sources/plugins/restricted/realmInfo.rst.txt @@ -0,0 +1,20 @@ +========== +realmInfo +========== + +Display information about a bastion realm +========================================= + + +.. admonition:: usage + :class: cmdusage + + --osh realmInfo --realm REALM + +.. program:: realmInfo + + +.. option:: --realm REALM + + Name of the realm to show info about + diff --git a/_sources/plugins/restricted/realmList.rst.txt b/_sources/plugins/restricted/realmList.rst.txt new file mode 100644 index 0000000..ccad425 --- /dev/null +++ b/_sources/plugins/restricted/realmList.rst.txt @@ -0,0 +1,20 @@ +========== +realmList +========== + +List the bastions realms +======================== + + +.. admonition:: usage + :class: cmdusage + + --osh realmList [--realm REALM] + +.. program:: realmList + + +.. option:: --realm REALM + + Only list the specified realm (mainly: check if it exists) + diff --git a/_sources/plugins/restricted/rootListIngressKeys.rst.txt b/_sources/plugins/restricted/rootListIngressKeys.rst.txt new file mode 100644 index 0000000..b85df93 --- /dev/null +++ b/_sources/plugins/restricted/rootListIngressKeys.rst.txt @@ -0,0 +1,19 @@ +==================== +rootListIngressKeys +==================== + +List the public keys to connect as root on this bastion +======================================================= + + +.. admonition:: usage + :class: cmdusage + + --osh rootListIngressKeys + +.. program:: rootListIngressKeys + + +This command is mainly useful for auditability purposes. +As it gives some information as to who can be root on the underlying system, +please grant this command only to accounts that need to have this information. diff --git a/_sources/plugins/restricted/selfAddPersonalAccess.rst.txt b/_sources/plugins/restricted/selfAddPersonalAccess.rst.txt new file mode 100644 index 0000000..68f72bd --- /dev/null +++ b/_sources/plugins/restricted/selfAddPersonalAccess.rst.txt @@ -0,0 +1,89 @@ +====================== +selfAddPersonalAccess +====================== + +Add a personal server access to your account +============================================ + + +.. admonition:: usage + :class: cmdusage + + --osh selfAddPersonalAccess --host HOST --user USER --port PORT [OPTIONS] + +.. program:: selfAddPersonalAccess + + +.. option:: --host HOST|IP|NET/CIDR + + Host(s) to add access to, either a HOST which will be resolved to an IP immediately, + + or an IP, or a whole network using the NET/CIDR notation + --user USER|PATTERN|* Specify which remote user should be allowed to connect as. + Globbing characters '*' and '?' are supported, so you can specify a pattern + that will be matched against the actual remote user name. + To allow any user, use '--user *' (you might need to escape '*' from your shell) + --port PORT|* Remote port allowed to connect to + To allow any port, use '--port *' (you might need to escape '*' from your shell) +.. option:: --protocol PROTO + + Specify that a special protocol should be allowed for this HOST:PORT tuple, note that you + + must not specify --user in that case. However, for this protocol to be usable under a given + remote user, access to the USER@HOST:PORT tuple must also be allowed. + PROTO must be one of: + scpup allow SCP upload, you--bastion-->server + scpdown allow SCP download, you<--bastion--server + sftp allow usage of the SFTP subsystem, through the bastion + rsync allow usage of rsync, through the bastion +.. option:: --force + + Add the access without checking that the public SSH key is properly installed remotely + +.. option:: --force-key FINGERPRINT + + Only use the key with the specified fingerprint to connect to the server (cf selfListEgressKeys) + +.. option:: --force-password HASH + + Only use the password with the specified hash to connect to the server (cf selfListPasswords) + +.. option:: --ttl SECONDS|DURATION + + Specify a number of seconds (or a duration string, such as "1d7h8m") after which the access will automatically expire + +.. option:: --comment "'ANY TEXT'" + + Add a comment alongside this server. Quote it twice as shown if you're under a shell. + + +Plugin configuration +==================== + +Options +------- + +.. option:: widest_v4_prefix (optional, integer, between 0 and 32) + + When specified, this limits the size of prefixes that can be added to an + ACL, e.g. 24 would not allow prefixes wider than /24 (such as /20 or + /16). + Note that this doesn't prevent users from adding thousands of ACLs to + cover a wide range of networks, but this helps ensuring ACLs such as + 0.0.0.0/0 can't be added in a single command. + +.. option:: self_remote_user_only (optional, boolean) + + When true, this only allows to add ACLs with the remote user being the + same than the account name, i.e. a bastion account named "johndoe" would + only be able to use ``selfAddPersonalAccess --user johndoe``. + +Example +------- + +Configuration, in JSON format, must be in :file:`/etc/bastion/plugin.selfAddPersonalAccess.conf`: + +.. code-block:: json + :emphasize-lines: 1 + + { "widest_v4_prefix": 24, "self_remote_user_only": true } diff --git a/_sources/plugins/restricted/selfDelPersonalAccess.rst.txt b/_sources/plugins/restricted/selfDelPersonalAccess.rst.txt new file mode 100644 index 0000000..c8666a1 --- /dev/null +++ b/_sources/plugins/restricted/selfDelPersonalAccess.rst.txt @@ -0,0 +1,37 @@ +====================== +selfDelPersonalAccess +====================== + +Remove a personal server access from your account +================================================= + + +.. admonition:: usage + :class: cmdusage + + --osh selfDelPersonalAccess --host HOST --user USER --port PORT [OPTIONS] + +.. program:: selfDelPersonalAccess + + +.. option:: --host HOST|IP|NET/CIDR + + Host(s) to remove access from, either a HOST which will be resolved to an IP immediately, + + or an IP, or a whole network using the NET/CIDR notation + --user USER|PATTERN|* Specify which remote user was allowed to connect as. + Globbing characters '*' and '?' are supported, so you can specify a pattern + that will be matched against the actual remote user name. + If any user was allowed, use '--user *' (you might need to escape '*' from your shell) + --port PORT|* Remote port that was allowed to connect to + If any port was allowed, use '--port *' (you might need to escape '*' from your shell) +.. option:: --protocol PROTO + + Specify that a special protocol allowance should be removed from this HOST:PORT tuple, note that you + + must not specify --user in that case. + PROTO must be one of: + scpup allow SCP upload, you--bastion-->server + scpdown allow SCP download, you<--bastion--server + sftp allow usage of the SFTP subsystem, through the bastion + rsync allow usage of rsync, through the bastion diff --git a/_sources/plugins/restricted/whoHasAccessTo.rst.txt b/_sources/plugins/restricted/whoHasAccessTo.rst.txt new file mode 100644 index 0000000..24ba23a --- /dev/null +++ b/_sources/plugins/restricted/whoHasAccessTo.rst.txt @@ -0,0 +1,47 @@ +=============== +whoHasAccessTo +=============== + +List the accounts that have access to a given server +==================================================== + + +.. admonition:: usage + :class: cmdusage + + --osh whoHasAccessTo --host SERVER [OPTIONS] + +.. program:: whoHasAccessTo + + +.. option:: --host SERVER + + List declared accesses to this server + +.. option:: --user USER + + Remote user allowed (if not specified, ignore user specifications) + +.. option:: --port PORT + + Remote port allowed (if not specified, ignore port specifications) + +.. option:: --ignore-personal + + Don't check accounts' personal accesses (i.e. only check groups) + +.. option:: --ignore-group GROUP + + Ignore accesses by this group, if you know GROUP public key is in fact + + not present on remote server but bastion thinks it is +.. option:: --show-wildcards + + Also list accesses that match because 0.0.0.0/0 is listed in a group or private access, + + this is disabled by default because this is almost always just noise (see Note below) + +Note: This list is what the bastion THINKS is true, which means that if some group has 0.0.0.0/0 in its list, +then it'll show all the members of that group as having access to the machine you're specifying, through this group key. +This is only true if the remote server does have the group key installed, of course, which the bastion +can't tell without trying to connect "right now" (which it won't do). diff --git a/_sources/presentation/features.rst.txt b/_sources/presentation/features.rst.txt new file mode 100644 index 0000000..436c0d0 --- /dev/null +++ b/_sources/presentation/features.rst.txt @@ -0,0 +1,31 @@ +======== +Features +======== + +.. note:: + This aims to be a quick overview of the main supported features of The Bastion, focusing on use cases. + For a better introduction about the basic features, please refer to the front page of the documentation. + +.. warning:: + Documentation might not be present yet for all the features below. + +- Personal and group access schemes with group roles delegation to ensure teams autonomy without security trade-offs +- SSH protocol break between the ingress and egress connections (see other :doc:`security measures`) +- Self-reliance achieved through virtually no external dependencies (see other :doc:`security measures`) +- Interactive session recording (in standard ``ttyrec`` files) +- Non-interactive session recording (`stdout` and `stderr` through ``ttyrec``) +- Extensive logging support through `syslog` for easy SIEM consumption +- Supports `MOSH `_ on the ingress connection side +- Supports ``scp`` passthrough, to upload and/or download files from/to remote servers +- Supports ``netconf`` SSH subsystem passthrough +- Supports Yubico PIV keys + `attestation checking `_ and enforcement + on the ingress connection side +- Supports realms, to create a trust between two bastions of possibly two different companies, + splitting the authentication and authorization phases while still enforcing local policies +- Supports SSH password autologin on the egress side for legacy devices not supporting pubkey authentication, + while still forcing proper pubkey authentication on the ingress side +- Supports telnet password autologin on the egress side for ancient devices not supporting SSH, + while still forcing proper SSH pubkey authentication on the ingress side +- Supports HTTPS proxying with man-in-the-middle authentication and authorization handling, + for ingress and egress password decoupling (mainly useful for network device APIs) diff --git a/_sources/presentation/principles.rst.txt b/_sources/presentation/principles.rst.txt new file mode 100644 index 0000000..c2a6e5a --- /dev/null +++ b/_sources/presentation/principles.rst.txt @@ -0,0 +1,12 @@ +========== +Principles +========== + +.. note:: + Most of the principles of The Bastion are well explained in the **Part 2** of the blog post + that announced the release. The links are below. + +- `Part 1 - Genesis `_ +- `Part 2 - Delegation Dizziness `_ +- `Part 3 - Security at the Core `_ +- `Part 4 - A new era `_ diff --git a/_sources/presentation/security.rst.txt b/_sources/presentation/security.rst.txt new file mode 100644 index 0000000..6407d89 --- /dev/null +++ b/_sources/presentation/security.rst.txt @@ -0,0 +1,61 @@ +======== +Security +======== + +Security principles at the core +=============================== + +Even with the most conservative, precautionous and paranoid coding process, code has bugs, +so it shouldn't be trusted blindly. Hence the bastion doesn't trust its own code. +It leverages the operating system security primitives to get additional security, as seen below. + +- Uses the well-known and trusted UNIX Discretionary Access Control: + + - Bastion users are mapped to actual system users + - Bastion groups are mapped to actual system groups + - All the code is constantly checking rights before allowing any action + - UNIX DAC is used as a safety belt to prevent an action from succeeding even if the code + is tricked into allowing it + +- The bastion main script is declared as the bastion user's system shell: + + - No user has real (``bash``-like) shell access on the system + - All code is ran under the unprivileged user's system account rights + - Even if a user could escape to a real shell, they wouldn't be able to connect to machines they don't have + access to, because they don't have filesystem-level read access to the SSH keys + +- The code is modular + + - The main code mainly checks rights, logs actions, and enable ``ssh`` access to other machines + - All side commands, called **plugins**, are in modules separated from the main code + - The modules can either be **open** or **restricted** + + - Only accounts that have been specifically granted on a need-to-use basis can run a specific restricted plugin + - This is checked by the code, and also enforced by UNIX DAC (the plugin is only readable and + executable by the system group specific to the plugin) + +- All the code needing extended system privileges is separated from the main code, in modules called **helpers** + + - Helpers are run exclusively under ``sudo`` + - The ``sudoers`` configuration is attached to a system group specific to the command, + which is granted to accounts on a need-to-use basis + - The helpers are only readable and executable by the system group specific to the command + - The helpers path and some of their immutable parameters are hardcoded in the ``sudoers`` configuration + - Perl tainted mode (``-T``) is used for all code running under ``sudo``, preventing any user-input to + interfere with the logic, by halting execution immediately + - Code running under ``sudo`` doesn't trust its caller and re-checks every input + - Communication between unprivileged and privileged-code are done using JSON + +Auditability +============ + +- Bastion administrators must use the bastion's logic to connect to itself to administer it (or better, + use another bastion to do so), this ensures auditability in all cases + +- Every access and action (whether allowed or denied) is logged with: + + - ``syslog``, which should also be sent to a remote syslog server to ensure even + bastion administrators can't tamper their tracks, and/or + - local ``sqlite3`` databases for easy searching + +- This code is used in production in several PCI-DSS, ISO 27001, SOC1 and SOC2 certified environments diff --git a/_sources/using/api.rst.txt b/_sources/using/api.rst.txt new file mode 100644 index 0000000..756101a --- /dev/null +++ b/_sources/using/api.rst.txt @@ -0,0 +1,266 @@ +======== +JSON API +======== + +.. contents:: + +Introduction +============ + +The Bastion has a JSON API that can be used to interact with :ref:`plugins`. + +Instead of exposing a specific HTTPS port for this API, The Bastion leverages its already exposed protocol, SSH, +to expose its API through it. The rationale is: + +- Avoid exposing a new port and a new protocol (HTTPS) to avoid widening the attack surface +- Leverage the pre-existing authentication and user isolation mechanisms implemented by The Bastion behind SSH + +This API is implemented for all :ref:`plugins `, and can be enabled by the ``--json*`` series of options. + +.. note:: + + Within this page, the ``bssh`` bastion alias we usually use through the documentation is replaced by + explicit ``ssh`` commands, to emphasize the fact that as we're doing M2M calls, + there would be no terminal involved, hence we shouldn't use the ``-t`` SSH option to connect to the bastion + (as is the case with the ``bssh`` alias). + +Adding either ``--json``, ``--json-pretty`` or ``--json-greppable`` to your ``--osh`` commands enable +the JSON API output. Here is an example of each one below. + +Examples +======== + +Using --json-pretty +------------------- + +Let's start with ``--json-pretty``: + +.. code-block:: shell + :emphasize-lines: 1 + + ssh robot-group@bastion1.example.org -- --osh groupListServers --group mygroup --json-pretty + ╭──ac777d06bec9───────────────────────────────────────────the-bastion-3.12.00─── + │ ▶ list of servers pertaining to the group + ├─────────────────────────────────────────────────────────────────────────────── + │ IP PORT USER ACCESS-BY ADDED-BY ADDED-AT + │ --------- ---- ----- -------------- -------- ---------- + │ 127.1.2.3 22 (any) mygroup(group) johndoe 2023-07-31 + │ + │ 1 accesses listed + + JSON_START + { + "command" : "groupListServers", + "value" : [ + { + "port" : "22", + "expiry" : null, + "forcePassword" : null, + "forceKey" : null, + "addedBy" : "johndoe", + "userComment" : null, + "comment" : null, + "user" : null, + "ip" : "127.1.2.3", + "addedDate" : "2023-07-31 08:56:05", + "reverseDns" : null + } + ], + "error_code" : "OK", + "error_message" : "OK" + } + + JSON_END + ╰──────────────────────────────────────────────────────────── + +As you see, adding ``--json-pretty`` to the command enables output of additional text that can be parsed as JSON. +This option is the most human-readable one, and encloses the JSON output between two anchors, namely +``JSON_START`` and ``JSON_END``. All the text output out of these anchors can be ignored for the JSON API parsing. + +Here is an example of parsing using simple shell commands: + +.. code-block:: shell + :emphasize-lines: 1,2 + + ssh robot-group@bastion1.example.org -- --osh groupListServers --group mygroup --json-pretty --quiet | \ + awk '/^JSON_END\r?$/ {if(P==1){exit}} { if(P==1){print} } /^JSON_START\r?$/ {P=1}' | jq . + { + "error_code": "OK", + "error_message": "OK", + "value": [ + { + "userComment": null, + "reverseDns": null, + "expiry": null, + "user": null, + "forceKey": null, + "addedDate": "2023-07-31 08:56:05", + "port": "22", + "addedBy": "johndoe", + "ip": "127.1.2.3", + "forcePassword": null, + "comment": null + } + ], + "command": "groupListServers" + } + +Note that we use ``--quiet``, which removes some text that is only useful to humans, and it also disables colors +in the output. In any case, the JSON API output between the anchors never has colors enabled. + +Using --json +------------ + +This option uses the same anchors than ``--json-pretty``, but doesn't prettify the JSON, so the output +is more compact: + +.. code-block:: shell + :emphasize-lines: 1 + + ssh robot-group@bastion1.example.org -- --osh groupListServers --group mygroup --json + ---ac777d06bec9-------------------------------------------the-bastion-3.12.00--- + => list of servers pertaining to the group + -------------------------------------------------------------------------------- + ~ IP PORT USER ACCESS-BY ADDED-BY ADDED-AT + ~ --------- ---- ----- ------------------ -------- ---------- + ~ 127.1.2.3 22 (any) mygroup(group) johndoe 2023-07-31 + ~ + ~ 1 accesses listed + + JSON_START + {"error_code":"OK","error_message":"OK","value":[{"forcePassword":null,"expiry":null,"port":"22","addedBy":"johndoe","ip":"127.1.2.3","userComment":null,"addedDate":"2023-07-31 08:56:05","user":null,"reverseDns":null,"comment":null,"forceKey":null}],"command":"groupListServers"} + JSON_END + +As the anchors are the same, the parsing can be done with the same logic as above: + +.. code-block:: shell + :emphasize-lines: 1,2 + + ssh robot-group@bastion1.example.org -- --osh groupListServers --group mygroup --json --quiet | \ + awk '/^JSON_END\r?$/ {if(P==1){exit}} { if(P==1){print} } /^JSON_START\r?$/ {P=1}' | jq . + { + "error_code": "OK", + "error_message": "OK", + "value": [ + { + "userComment": null, + "reverseDns": null, + "expiry": null, + "user": null, + "forceKey": null, + "addedDate": "2023-07-31 08:56:05", + "port": "22", + "addedBy": "johndoe", + "ip": "127.1.2.3", + "forcePassword": null, + "comment": null + } + ], + "command": "groupListServers" + } + +Using --json-greppable +---------------------- + +This is a variant of the ``--json`` option, but instead of relying on ``JSON_START`` and ``JSON_END`` anchors, +which works for both ``--json`` and ``--json-pretty`` modes, here the JSON output is packed on one line, +starting with the ``JSON_OUTPUT=`` anchor. +You may use the option that is the easier for you to parse in your script or calling program. + +.. code-block:: shell + :emphasize-lines: 1 + + ssh robot-group@bastion1.example.org -- --osh groupListServers --group mygroup --json--greppable + ---ac777d06bec9-------------------------------------------the-bastion-3.12.00--- + => list of servers pertaining to the group + -------------------------------------------------------------------------------- + ~ IP PORT USER ACCESS-BY ADDED-BY ADDED-AT + ~ --------- ---- ----- ------------------ -------- ---------- + ~ 127.1.2.3 22 (any) mygroup(group) johndoe 2023-07-31 + ~ + ~ 1 accesses listed + + JSON_OUTPUT={"error_code":"OK","command":"groupListServers","error_message":"OK","value":[{"reverseDns":null,"userComment":null,"user":null,"forceKey":null,"port":"22","addedDate":"2023-07-31 08:56:05","expiry":null,"addedBy":"johndoe","ip":"127.1.2.3","comment":null,"forcePassword":null}]} + ------------------------------------------------------------- + +Here is an example of parsing using simple shell commands: + +.. code-block:: shell + :emphasize-lines: 1,2 + + ssh robot-group@bastion1.example.org -- --osh groupListServers --group mygroup --json-greppable --quiet | \ + grep ^JSON_OUTPUT= | cut -d= -f2- | jq . + { + "error_code": "OK", + "error_message": "OK", + "value": [ + { + "userComment": null, + "reverseDns": null, + "expiry": null, + "user": null, + "forceKey": null, + "addedDate": "2023-07-31 08:56:05", + "port": "22", + "addedBy": "johndoe", + "ip": "127.1.2.3", + "forcePassword": null, + "comment": null + } + ], + "command": "groupListServers" + } + + +JSON payload format +=================== + +The JSON payload is always a hash with 4 keys: ``error_code``, ``error_message``, ``value`` and ``command``, +as you may have witnessed from the examples above. + +These keys are detailed below. + +command +------- + +The associated value is a string, containing the name of the command (plugin) that generated this output. + +error_code +---------- + +The associated value is an always-uppercase string. You should look at the prefix of this string to know +whether the command was a success or not. The value is never ``null`` and always matches the following regex: +``^(OK|KO|ERR)[A-Z0-9_]*$``. The possible prefixes are either: + +- ``OK``: the command has succeeded +- ``KO``: the command did not succeed +- ``ERR``: the command encountered an error, more information should be available in the ``error_message`` field, + the ``value`` field will most likely be ``null`` + +Examples of such values include: ``KO_ACCESS_DENIED``, ``OK``, ``OK_NO_CHANGE``, ``ERR_MEMBER_CANNOT_BE_GUEST``. + +You should rely on these error codes in the code using The Bastion's API to take decisions. + +error_message +------------- + +The associated value is a string, intended for human reading. It gives more details about the returned ``error_code``, +but is not intended to be parsed by your code, as it may change without notice from version to version. If there is no +specific ``error_message`` for a given case, the value will be the same than the one for ``error_code``, hence this +field is guaranteed to always exist and never be ``null``. + +value +----- + +The data associated to the key ``value`` is entirely dependent on ``command``, and can be a nested structure of +hashes and/or arrays. This is the actual data payload returned by the command you've invoked. Note that ``value`` +can also be ``null``, particularly if the ``error_code`` doesn't start with the ``OK`` prefix. + +Good practices +============== + +If you're intending interaction with The Bastion API, it's a good idea to have accounts dedicated to this, to have +a clear distinction between human SSH usage and automated API calls. Additionally, if your automation will only +use such accounts to call plugins (``--osh`` commands), you might want to create such accounts with the ``--osh-only`` +parameter to ``accountCreate``, this guarantees that such accounts will never be able to use The Bastion to connect +to other infrastructures (e.g. using SSH) even if granted to. diff --git a/_sources/using/basics/access_management.rst.txt b/_sources/using/basics/access_management.rst.txt new file mode 100644 index 0000000..9953f83 --- /dev/null +++ b/_sources/using/basics/access_management.rst.txt @@ -0,0 +1,146 @@ +================= +Access management +================= + +There are two ways of managing authorizations on The Bastion, it is extremely important +to understand those two ways because they're complementary. + +.. note:: + This section is largely inspired from the `blog post about the subject + `_ + +The main idea is that delegation is at the core of the system: everybody has their own set of responsibilities, +and potential actions, without having to ask the bastion admin. + +.. _accessManagementPersonalAccesses: + +Personal Accesses +================= + +On the bastion, each account has (at least) one set of **personal egress keys**. +These beasts are generated when the account is first created. +The personal egress **private key** sits in the bastion account home. +The account user has no way to see it, or export it out of the bastion, +but they can use it through the bastion's code logic. +The user can retrieve the corresponding **public key** at any time, using the :doc:`/plugins/open/selfListEgressKeys` +command, and install it – or get it installed – on the remote servers they needs to access. +Depending on your use case – and the level of autonomy you want to give to the teams – there are +two ways of managing these personal accesses. + +Decentralized (help yourself) +***************************** + +The first way mimics how you would manage accesses if you weren't using an SSH bastion at all. +This is a perfectly valid way to handle accesses on a simple level, without too many users and a limited +number of machines. This allows anyone to grant themselves personal accesses on the bastion, +without having to ask anyone else to do it. It sounds like a security hole, but it's not. +If someone adds themself a personal access to the remote server, it will only work if their +personal egress public key has already been installed on the remote server. +In other words, they either already had access to the remote server to do this – using means other than the bastion – +or somebody who had access to the remote server accepted the addition of their key. +Either way, they cannot magically grant themselves personal access without +the admins of the remote server first permitting their key. + +Centralized (ask the IT crowd) +****************************** + +Another way to handle this can be to grant a limited number of people, such as security teams, +the right to add personal accesses to others. This way people are less autonomous, but it might be useful +if adding accesses has to be enacted via normalized processes. It also has some nice effects: as a sysadmin, +one of the pros is that you can create 3 separate accounts on the remote machine, and map them to each bastion account +you're adding. This is a good method for achieving **end-to-end traceability**; including on the remote server; +where you might want to install **auditd** or similar tools. +It's also doable in the help yourself mode, but it may be harder to enforce. + +To be clear, this access model doesn't scale so efficiently when we're dealing with whole teams, +or big infrastructures – this is where group-based access comes handy. + +.. _accessManagementGroupAccesses: + +Group Accesses +============== + +.. image:: /img/groups.png + :width: 400px + +A group has three components: + +- A list of members (accounts, representing individual people) +- At least one set of group egress keys +- A list of servers (or more precisely IPs) + +Servers list +************ + +The servers list is actually a list of IPs, or IP blocks. They map to your servers, network devices, +or anything else with SSH capability that has an IP (on which the egress group key has been installed). +Technically, this list is actually composed of 3-tuple items: remote user, remote IP (or IP block), remote port. +That which applies to the personal accesses, also applies here: adding a server to the list doesn't magically +give access to it, it is first necessary to install the **egress group public key**. +Of course, managing the installation of these keys manually quickly becomes impractical, +but you can consider these part of the configuration of the servers, hence they should be managed with whichever +centralized configuration system you already use (Puppet, Chef, Ansible, /bin/cp… wait, no, strike this last one). + +Members list +************ + +The members are people who can connect to any server listed in the group server list. +They'll be using the **private egress group key** they have access to, as members of said group. +Of course, they have no way to extract this private key for their own use outside of the bastion, +they can only use it through the bastion's code logic. + +Got a new team member? Just add them as a member of your group, and they instantly get access to all the group servers. +Somebody leaves the company? Just delete their account on the bastion, and all the accesses are instantly gone. +This is the case because all your servers should have incoming SSH sessions limited to your bastions. +This way, any rogue SSH key that would have been added, is no longer of any use. + +.. _accessManagementGroupRoles: + +And some more +************* + +We've covered the basics of the group-based approach, but as we need a lot of flexibility and delegation, +there is a little more to cover. Remember when I said a group had 3 components? Well, I lied. +A group has more than just members. Additional group roles include: + +- Guests +- Gatekeepers +- Aclkeepers +- Owners + +All of these are lists of accounts that have a specific role in the group. + +.. image:: /img/group_roles.png + +First, **guests**. These are a bit like members, but with less privileges: they can connect to remote machines +using the group key, but not to all the machines of the group, only to a subset. +This is useful when somebody outside of the team needs a specific access to a specific server, +potentially for a limited amount of time (as such accesses can be set to expire). + +Then, **gatekeepers**. Those guys manage the list of members and guests of the group. +In other terms, they have the right to give the right to get access. Nothing too complicated here. +Then, there are the **aclkeepers**. As you may have guessed, they manage the list of servers that are +part of the group. If you happen to have some automation managing the provisioning of servers of your infrastructure, +this role could be granted to a robot account whose sole purpose would be to update the servers list on the bastion, +in a completely integrated way with your provisioning. +You can even tag such accounts so that they'll never be able to use SSH through the bastion, +even if somebody grants them by mistake! + +Last but not least, the **owners** have the highest privilege level on the group, which means they can manage +the gatekeepers, aclkeepers and owners lists. They are permitted to give the right to give the right to get access. +Moreover, users can accumulate these roles, which means some accounts may be a member +and a gatekeeper at the same time, for example. + +Global roles +============ + +Beyond the roles we have just described – which are all scoped to a group – there are two additional roles, +which are scoped to the whole bastion: the **superowner** and the **bastion admin**. + +In a nutshell, a **superowner** is the implicit owner of all groups present on the bastion. +This comes in handy if the group becomes ownerless, as superowners are able to nominate a brand new owner. + +The most powerful role is the **bastion admin**. This role should only be given to a few individuals, +as they can impersonate anyone, and in practice should not be given to somebody who is not already root +on the bastion's operating system itself. Among other things, they manage the configuration of the bastion, +where the superowners are declared. diff --git a/_sources/using/basics/first_steps.rst.txt b/_sources/using/basics/first_steps.rst.txt new file mode 100644 index 0000000..936630e --- /dev/null +++ b/_sources/using/basics/first_steps.rst.txt @@ -0,0 +1,270 @@ +=========== +First steps +=========== + +Bastion alias +************* + +You should setup a *bastion alias* to make it easy to connect to the bastion. +An example of the proper alias to use for your account is given to the bastion administrator +when they creates your account, and is usually something along the lines of: + +.. code-block:: shell + :emphasize-lines: 1 + + alias bssh='ssh -t myname@the-bastion.example.org --' + +Of course, you can modify it as you see fit, for example adding the ``-i`` argument to specify the private SSH key +to use to connect to the bastion. You can use any name as the alias, +but it's advised to keep it short, as you'll use it quite often. + +For the remaining of this documentation, we'll assume your bastion alias is ``bssh``. + +You can do two categories of things on the bastion: + +- Connect to infrastructures through it +- Interact with the bastion itself, for example to manage your account, and/or groups, + through so-called **PLUGINS** aka *osh commands* + +Plugins +******* + +We'll start by using the ``info`` plugin, to verify that your bastion access works correctly: + +.. code-block:: shell + :emphasize-lines: 1 + + bssh --osh info + *------------------------------------------------------------------------------* + |THIS IS A PRIVATE COMPUTER SYSTEM, UNAUTHORIZED ACCESS IS STRICTLY PROHIBITED.| + |ALL CONNECTIONS ARE LOGGED. IF YOU ARE NOT AUTHORIZED, DISCONNECT NOW. | + *------------------------------------------------------------------------------* + Enter PIN for 'PIV Card Holder pin (PIV_II)': + ---the-bastion.example.org----------------------------the-bastion-2.99.99-rc9--- + => information + -------------------------------------------------------------------------------- + ~ You are johndoe + ~ You are a bastion auditor! + ~ Look at you, you are a bastion superowner! + ~ Woosh, you are even a bastion admin! + ~ + ~ Your alias to connect to this bastion is: + ~ alias bssh='ssh johndoe@the-bastion.example.org -p 22 -t -- ' + ~ Your alias to connect to this bastion with MOSH is: + ~ alias bsshm='mosh --ssh="ssh -p 22 -t" johndoe@the-bastion.example.org -- ' + ~ + ~ [...] + ~ + ~ Here is your excuse for anything not working today: + ~ BOFH excuse #46: + ~ waste water tank overflowed onto computer + ------------------------------------------------------------------------- + Connection to the-bastion.example.org closed. + +Congratulations, you've just used your first command on the bastion! + +You can get a list of all the plugins you can use by saying: + +.. code-block:: shell + :emphasize-lines: 1 + + bssh --osh help + +The list will depend on your access level on the bastion, as some commands are restricted. +You can have more information about any command by using ``--help`` with it: + +.. code-block:: shell + :emphasize-lines: 1 + + bssh --osh selfAddIngressKey --help + +See the **PLUGINS** section on the left menu, for more information about the plugins. + +Instead of using ``--osh`` to call plugins, you can enter the special *interactive mode*, by saying: + +.. code-block:: shell + :emphasize-lines: 1 + + bssh -i + +In this mode, you can directly enter commands, and also use auto-completion features with the ```` key. +You can start by just typing ``help``, which is the equivalent of saying ``bssh --osh help``. +For security reasons, the interactive mode will disconnect you after a given amount of idle-time. + +Setting up access to a server +***************************** + +.. note:: + + This section assumes that you've just set up your bastion and your account is the one that has been created + on installation, with all the super-powers included, especially access to the restricted + :doc:`/plugins/restricted/selfAddPersonalAccess` command that we'll use below. + If this is not the case, you'll need first to have a bastion admin grant you this command + through :doc:`/plugins/restricted/accountGrantCommand` + +Let's say that you have a server you want to secure access to, using the bastion. +We'll call it *server42.example.org*, with IP 198.51.100.42. +To do this, we'll use the :doc:`/plugins/restricted/selfAddPersonalAccess` command. + +We can use the interactive mode to get the auto-completion features: + +.. code-block:: shell + :emphasize-lines: 1 + + bssh -i + Enter PIN for 'PIV Card Holder pin (PIV_II)': + + Welcome to bssh interactive mode, type `help' for available commands. + You can use and for autocompletion. + You'll be disconnected after 60 seconds of inactivity. + Loading... 88 commands and 341 autocompletion rules loaded. + + bssh(master)> + +You can enter the first few characters of the command, then use ```` to help you complete it, +then use ```` again to show you the required arguments. The complete command would be as follows: + +.. code-block:: none + :emphasize-lines: 1 + + bssh(master)> selfAddPersonalAccess --host 198.51.100.42 --port 22 --user root + ---the-bastion.example.org----------------------------the-bastion-2.99.99-rc9--- + => adding private access to a server on your account + -------------------------------------------------------------------------------- + ~ Testing connection to root@198.51.100.42, please wait... + Warning: Permanently added '198.51.100.42' (ECDSA) to the list of known hosts. + root@198.51.100.42: Permission denied (publickey). + ~ Note: if you still want to add this access even if it doesn't work, use --force + ~ Couldn't connect to root@198.51.100.42 (ssh returned error 255). Hint: did you add the proper public key to the remote's authorized_keys? + -------------------------------------------------------- + bssh(master)> + +You'll notice that it didn't work. This is because first, you need to add your *personal egress key* to the +remote machine's *authorized_keys* file. If this seems strange, here is +:doc:`how it works `. +To get your *personal egress key*, you can use this command: + +.. code-block:: shell + :emphasize-lines: 1 + + bssh(master)> selfListEgressKeys + ---the-bastion.example.org----------------------------the-bastion-2.99.99-rc9--- + => the public part of your personal bastion key + -------------------------------------------------------------------------------- + ~ You can copy one of those keys to a remote machine to get access to it through your account + ~ on this bastion, if it is listed in your private access list (check selfListAccesses) + ~ + ~ Always include the from="198.51.100.1/32" part when copying the key to a server! + ~ + ~ fingerprint: SHA256:rMpoCaYPSfRqmOBFOJvEr5uLqxYjqYtRDgUoqUwH2nA (ED25519-256) [2019/07/11] + ~ keyline follows, please copy the *whole* line: + from="198.51.100.1/32" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILnY2NQTKsTDxgcaTE6vHVm9FIbud1rJcYQ/4xUyr+DK johndoe@bssh:1562861572 + ----------------------------------------------------------- + +Now that you have it, you can push this public key (the line starting with the *from=*) to the remote server's +root authorized_keys, i.e. ``/root/.ssh/authorized_keys``. Now, you can add your access properly: + +.. code-block:: shell + :emphasize-lines: 1 + + bssh(master)> selfAddPersonalAccess --host 198.51.100.42 --port 22 --user root + ---the-bastion.example.org----------------------------the-bastion-2.99.99-rc9--- + => adding private access to a server on your account + -------------------------------------------------------------------------------- + ~ Testing connection to root@198.51.100.42, please wait... + Warning: Permanently added '198.51.100.42' (ECDSA) to the list of known hosts. + ~ Access to root@198.51.100.42:22 successfully added + -------------------------------------------------------- + bssh(master)> + +All seems in order! Can we see this access we just created? + +.. code-block:: shell + :emphasize-lines: 1 + + bssh(master)> selfListAccesses + ---the-bastion.example.org----------------------------the-bastion-2.99.99-rc9--- + => your access list + -------------------------------------------------------------------------------- + ~ Dear johndoe, you have access to the following servers: + ~ IP PORT USER ACCESS-BY ADDED-BY ADDED-AT + ~ 198.51.100.42 22 root personal johndoe 2020-05-01 + -------------------------------------------------------- + bssh(master)> + +Connecting to a server and reviewing the session +************************************************ + +Good! Let's try to connect now! + +.. code-block:: shell + :emphasize-lines: 1 + + bssh(master)> ssh root@198.51.100.42 + ~ Welcome to the-bastion, johndoe, your last login was 00:13:37 ago (Fri 2020-08-28 13:07:43 UTC) from 192.0.2.11(proxy-11.example.org) + + proxy-11.example.org:40610 => johndoe@the-bastion.example.org:22 => root@server42.example.org:22 ... + allowed ... log on(/home/johndoe/ttyrec/198.51.100.42/2020-08-28.13-07-45.497020.fb00e1957b22.johndoe.root.198.51.100.42.22.ttyrec) + + will try the following accesses you have: + - personal access with ED25519-256 key SHA256:rMpoCaYPSfRqmOBFOJvEr5uLqxYjqYtRDgUoqUwH2nA [2019/07/11] + + Connecting... + + root@server42:~# id + uid=0(root) gid=0(root) groups=0(root),2(bin) + root@server42:~# + +We're now connected to server42, and can do our work as usual. Note that to connect to server42, one can directly use: + +.. code-block:: shell + :emphasize-lines: 1 + + bssh root@198.51.100.42 + +Where ``bssh`` is the bastion alias we've just set up above, no need to enter interactive mode first of course. + +When we're done with server42, let's see if everything was correctly recorded: + +.. code-block:: shell + :emphasize-lines: 1 + + bssh(master)> selfListSessions --type ssh --detailed + ---the-bastion.example.org---------------------the-bastion-2.99.99-rc9.2-ovh1--- + => your past sessions list + -------------------------------------------------------------------------------- + ~ The list of your 100 past sessions follows: + ~ + f4cca44a848e [2020/08/26@09:28:57 - 2020/08/26@09:29:57 ( 60.0)] type ssh from 192.0.2.11:33450(proxy-11.example.org) via johndoe@198.51.100.1:22 to root@198.51.100.42:22(server42.example.org) returned 0 + ------------------------------------------------------------- + +The first column is the unique identifier of the connection (or osh command). +Let's see what we did exactly during this session: + + +.. code-block:: none + :emphasize-lines: 1 + + bssh(master)> selfPlaySession --id f4cca44a848e + ---the-bastion.example.org---------------------the-bastion-2.99.99-rc9.2-ovh1--- + => replay a past session + -------------------------------------------------------------------------------- + ~ ID: f4cca44a848e + ~ Started: 2020/08/26 09:28:57 + ~ Ended: 2020/08/26 09:29:57 + ~ Duration: 0d+00:01:00.382820 + ~ Type: ssh + ~ From: 192.0.2.11:33450 (proxy-11.example.org) + ~ Via: johndoe@198.51.100.1:22 + ~ To: root@198.51.100.42:22 (server42.example.org) + ~ RetCode: 0 + ~ + ~ Press '+' to play faster + ~ Press '-' to play slower + ~ Press '1' to restore normal playing speed + ~ + ~ When you're ready to replay session 9f352fd4b85c, press ENTER. + ~ Starting from the next line, the Total Recall begins. Press CTRL+C to jolt awake. + +Now that you've connected to your first server, using a personal access, +you may want to learn more about the :doc:`access_management`, or directly dive into the **PLUGINS** on the left menu. diff --git a/_sources/using/basics/index.rst.txt b/_sources/using/basics/index.rst.txt new file mode 100644 index 0000000..63c39ad --- /dev/null +++ b/_sources/using/basics/index.rst.txt @@ -0,0 +1,16 @@ +========== +The basics +========== + +This section explains the basics you need to know to work with the bastion. +It's advised to go through all the subsections. + +We make the assumption here that you already have a bastion account: + +- either you're one of the admins who just :doc:`installed<../../installation/basic>` it, or +- one of the admins created an account for you, using :doc:`/plugins/restricted/accountCreate` + +.. toctree:: + + first_steps + access_management diff --git a/_sources/using/http_proxy.rst.txt b/_sources/using/http_proxy.rst.txt new file mode 100644 index 0000000..1080b13 --- /dev/null +++ b/_sources/using/http_proxy.rst.txt @@ -0,0 +1,240 @@ +=========== +HTTPS Proxy +=========== + +.. contents:: + +Introduction +============ + +In addition to securing your SSH accesses, by splitting the authentication part (ingress connection) +and the authorization part (egress connection), The Bastion can do a similar job for HTTPS connections. + +Note that there is an overhead (depending on your hardware setup) of several hundreds of milliseconds +for each query-response trip, due to the fact that multiple processes are spawned for each query, +to ensure proper security containment to the calling account's system user. +It's probably a bad idea to use on a multi-million queries/day workload, +or if each added millisecond to the query-response trip impacts the QoS of your service. + +The primary use is for network devices, that happen to have more and more HTTPS APIs in addition +to the usual ``conf terminal`` available through SSH. As the same commands are usually available from +HTTPS and SSH on these devices, it would be too bad to secure the access to SSH through the bastion, +but leave direct access to their HTTPS API! + +Query workflow +============== + +The workflow is similar to the one used by SSH, e.g. two distinct connections (ingress and egress), +with the egress connection using credentials stored on the bastion: + +- A client makes an HTTP request to the proxy, with the following information embedded in: + + - The type of request (GET or POST) + - The complete URI, including the host of the remote HTTPS server it would like to send the request to + - Potential body data for POST requests + - Credentials to authenticate to the proxy on the ingress connection, namely the + bastion account name and its proxy password (set by ``selfGenerateProxyPassword``) + - User name to use to authenticate on the remote HTTPS server (for the egress connection) + +- The bastion checks the provided credentials to authenticate the request against a known account (authentication part) +- The bastion verifies whether the just-authenticated account has access rights to connect to the remote server + as the specified remote user (authorization part) +- The bastion uses the (group or personal) credentials stored on the bastion, + to passthrough the HTTP request to the remote server, as the specified remote user +- The bastion forwards the response to the client + +Setting up the HTTPS Proxy +========================== + +You should enable the HTTPS Proxy daemon, and configure it. +Please check the :doc:`/administration/configuration/osh-http-proxy_conf` for more information. + +Running a query through the proxy +================================= + +First try +--------- + +Once the proxy is running, we can try to query it: + +.. code-block:: none + :emphasize-lines: 1 + + curl https://bastion1.example.org:8443/ + No authentication provided, and authentication is mandatory + +Of course, the proxy only accepts to work when one is properly authenticated to it. +To do this, one should have an account on the bastion, and use the :doc:`/plugins/open/selfGenerateProxyPassword` +command so that a new ingress password is set for their account. They'll then be able to authenticate to the proxy +using the HTTP basic-auth method, and try to send a request to a remote server. +To keep a high compatibility with HTTP clients and libraries that can be used on the ingress side, +all the additional data required by the bastion to properly authenticate, authorize and passthrough the request +is encoded in the *user* part of the widely supported HTTP Authorize header (basic-auth). +The *password* part corresponds to the password we've generated just above. + +The format of the *user* part is as follows: + +.. code-block:: none + + BASTION_ACCOUNT@REMOTE_USER@REMOTE_HOST%REMOTE_PORT + +The **%REMOTE_PORT** part is optional, and defaults to **443** if omitted. +For example, to send a **GET /info** request to the remote network device named **router12.example.org** on +the default port **443**, using the remote account **monitoring**, through the **bastion1.example.org** bastion, +having the HTTPS Proxy listening on its port **8443** and a bastion account **robot-mon**, one can use **curl**: + +.. code-block:: none + :emphasize-lines: 1 + + curl -u robot-mon@monitoring@router12.example.org https://bastion1.example.org:8443/info + Enter host password for user 'robot-mon@monitoring@router12.example.org': + This account doesn't have access to this user@host tuple (Access denied for robot-mon to monitoring@router12.example.org:443) + +A password will be prompted: the password generated by ``selfGenerateProxyPassword`` should be entered. +Remember: this is to authenticate yourself to the bastion (ingress connection), then the bastion will authenticate +itself to the remote machine (egress connection), using credentials stored on the bastion, +that your account must have access to. + +In the above case, we entered the password correctly, but our account doesn't have access to +the requested host `monitoring@router12.example.org`. This is what we need to do now. + +Access declaration +------------------ + +The access check is the same than the one done for SSH accesses, which means that oneself +can have access to a remote host either through a :ref:`personal access ` or +a :ref:`group access `. + +To get granted access to a remote device, through a personal access, either +the :doc:`/plugins/restricted/selfAddPersonalAccess` or the :doc:`/plugins/restricted/accountAddPersonalAccess` shall +be used (both are restricted commands) such as: + +.. code-block:: none + :emphasize-lines: 1 + + bssh --osh accountAddPersonalAccess --host router12.example.org --port 443 --user monitoring --force + +Note the use of ``--force`` to skip the SSH connection test, which is useless in our case. + +To use a group access instead, one of the :ref:`aclkeepers ` of the group +should use :doc:`/plugins/group-aclkeeper/groupAddServer`, such as: + +.. code-block:: none + :emphasize-lines: 1 + + bssh --osh groupAddServer --group netdevices --host router12.example.org --port 443 --user monitoring --force + + +Egress password +--------------- + +For personal accesses +********************* + +If access to a remote device is granted to you through a personal access (using either the ``selfAddPersonalAccess`` +or ``accountAddPersonalAccess`` commands), you must first generate a new set of credentials that will be stored +on your bastion account, for egress connections. This is the equivalent of your personal egress keys for SSH, +but in that case it's a password that will be used to authenticate using basic-auth to the remote server. +You can generate this password using the ``selfGeneratePassword`` command: + +.. code-block:: none + :emphasize-lines: 1 + + bssh --osh selfGeneratePassword --do-it + *------------------------------------------------------------------------------* + |THIS IS A PRIVATE COMPUTER SYSTEM, UNAUTHORIZED ACCESS IS STRICTLY PROHIBITED.| + |ALL CONNECTIONS ARE LOGGED. IF YOU ARE NOT AUTHORIZED, DISCONNECT NOW. | + *------------------------------------------------------------------------------* + ╭──bastion1.example.org───────────────────────────────the-bastion-3.03.99-rc1─── + │ ▶ generating a new egress password for your account + ├─────────────────────────────────────────────────────────────────────────────── + │ Generated a new password of length 16 for your account, robot-mon, hashes follow: + │ md5crypt: $1$G0fo$2DH2OJQJ9bMgo5fUUuPeK. + │ sha256crypt: $5$2xd1aGuD$ze7px3olXdjWthSrdnzelm6avzT2kszx/voXms8/V00 + │ sha512crypt: $6$udw2UNLs$tQ1p7ZYraOT4Woh1ZCGJNf.UAIh09nXPBf4ejpRurOY/fJUs6Dgh1WdkpY4pdCvKMQrPeetB42bNTSzIwJyGi1 + │ This new password will now be used by default. + ╰──────────────────────────────────────────────────────── + +As you can see, the password is stored on your bastion account, and is not printed: only its hashes are. +With this information, the corresponding remote account can be provisioned on the device (usually, a network device). +In our above example, an account named **monitoring** would have to be created on the remote device, +using one of these hashes. Prefer to use the most secure hashing algorithm supported by the remote device. + +To get your password (hash) list, you can use ``selfListPasswords``: + +.. code-block:: none + :emphasize-lines: 1 + + bssh --osh selfListPasswords + *------------------------------------------------------------------------------* + |THIS IS A PRIVATE COMPUTER SYSTEM, UNAUTHORIZED ACCESS IS STRICTLY PROHIBITED.| + |ALL CONNECTIONS ARE LOGGED. IF YOU ARE NOT AUTHORIZED, DISCONNECT NOW. | + *------------------------------------------------------------------------------* + ╭──bastion1.example.org───────────────────────────────the-bastion-3.03.99-rc1─── + │ ▶ list your egress passwords + ├─────────────────────────────────────────────────────────────────────────────── + │ Current password created at Tue Jun 22 15:42:10 2021 by robot-mon + │ ... md5crypt: $1$G0fo$2DH2OJQJ9bMgo5fUUuPeK. + │ ... sha256crypt: $5$2xd1aGuD$ze7px3olXdjWthSrdnzelm6avzT2kszx/voXms8/V00 + │ ... sha512crypt: $6$udw2UNLs$tQ1p7ZYraOT4Woh1ZCGJNf.UAIh09nXPBf4ejpRurOY/fJUs6Dgh1WdkpY4pdCvKMQrPeetB42bNTSzIwJyGi1 + │ + │ Fallback password 1 created at Wed Jun 2 08:00:01 2021 by robot-mon + │ ... md5crypt: $1$qF0M$2.rbRRGs66aPiEpc/SqGv/ + │ ... sha256crypt: $5$E9qkC7D6$SG8BB.nXvwU0dB0Bq9S/sF5pDidLwSIDKCv95qNWhX0 + │ ... sha512crypt: $6$druGNgSk$bzVHSvux/OOE2ZhDpabFekQU3GTsiKS7Yl/lLmb9gIAmjnFfR6gj7GzOniK2jdLtEcB/hQlhcx9TDgj5zHhVd. + │ + ╰─────────────────────────────────────────────────────────── + +If the ``selfGeneratePassword`` command is used several times, the newly generated password will always override +the previous one. Still, all the previous passwords are kept (archived) for good measure, and can be restored +manually by a bastion admin. These passwords are named *Fallback passwords* in the output of ``selfListPasswords``. + +For group accesses +****************** + +If the access to the remote device is given through a group, then the group's own credentials will be used. +To this effect, one of the group owners should use the :doc:`/plugins/group-owner/groupGeneratePassword` command: + +.. code-block:: none + :emphasize-lines: 1 + + bssh --osh groupGeneratePassword --group netdevices --do-it + ╭──bastion1.example.org───────────────────────────────the-bastion-3.03.99-rc1─── + │ ▶ generating a new egress password for the group + ├─────────────────────────────────────────────────────────────────────────────── + │ Generated a new password of length 16 for group netdevices, hashes follow: + │ md5crypt: $1$9sb2$X8/pPBSLfQ0ddBGR/bzsT1 + │ sha256crypt: $5$o6Jr8w0X$yQfLuX17tUwE1jfhhAX//vsn6KpXU5jUd7SCNbkYNH. + │ sha512crypt: $6$gyxMyjao$YNhZJPXZa4r838XKg2tfvvoV/Dtm5HKsyKt18BnvFfT.y.hZuSXRX9GhM4mA0hUsO9f0UBisO/WiK3vF/9qsL1 + │ This new password will now be used by default. + ╰─────────────────────────────────────────────────────── + +As with the personal egress passwords, the password is stored on the bastion only, and is not printed: +only its hashes are. With this information, the corresponding remote account can be provisioned +on the device (usually, a network device). +In our above example, an account named **monitoring** would have to be created on the remote device, +using one of these hashes. Prefer to use the most secure hashing algorithm supported by the remote device. + +To get the group's password (hash) list, one can use the :doc:`/plugins/open/groupListPasswords` command: + +.. code-block:: none + :emphasize-lines: 1 + + bssh --osh groupListPasswords --group netdevices + *------------------------------------------------------------------------------* + |THIS IS A PRIVATE COMPUTER SYSTEM, UNAUTHORIZED ACCESS IS STRICTLY PROHIBITED.| + |ALL CONNECTIONS ARE LOGGED. IF YOU ARE NOT AUTHORIZED, DISCONNECT NOW. | + *------------------------------------------------------------------------------* + ╭──bastion1.example.org───────────────────────────────the-bastion-3.03.99-rc1─── + │ ▶ list the egress passwords of the group + ├─────────────────────────────────────────────────────────────────────────────── + │ Current password created at Tue Jun 29 10:21:38 2021 by slesimpl + │ ... md5crypt: $1$9sb2$X8/pPBSLfQ0ddBGR/bzsT1 + │ ... sha256crypt: $5$o6Jr8w0X$yQfLuX17tUwE1jfhhAX//vsn6KpXU5jUd7SCNbkYNH. + │ ... sha512crypt: $6$gyxMyjao$YNhZJPXZa4r838XKg2tfvvoV/Dtm5HKsyKt18BnvFfT.y.hZuSXRX9GhM4mA0hUsO9f0UBisO/WiK3vF/9qsL1 + ╰────────────────────────────────────────────────────────── + +If the ``groupGeneratePassword`` command is used several times, the newly generated password will always +override the previous one. Still, all the previous passwords are kept (archived) for good measure, +and can be restored manually by a bastion admin. +These passwords are named *Fallback passwords* in the output of ``groupListPasswords``. diff --git a/_sources/using/piv.rst.txt b/_sources/using/piv.rst.txt new file mode 100644 index 0000000..b47324f --- /dev/null +++ b/_sources/using/piv.rst.txt @@ -0,0 +1,185 @@ +================ +PIV keys support +================ + +.. contents:: + +Introduction +============ + +The Bastion supports enabling a policy forcing accounts SSH ingress keys to originate from a known hardware token, +ensuring that the private SSH key is only stored on this hardware token, and not on the filesystem. + +Currently, only Yubico keys implementing PIV can be verified this way. In that case, each individual hardware token +has a builtin Certificate Authority, signed by a well-known Yubico certificate, hence proving that the hardware token +is known and legit. + +This builtin CA, in turn, emits an attestation certificate each time a new PIV key is generated on the hardware token, +hence proving that the bikey (private and public) has been generated by this individual hardware token. +Other metadata is included in the attestation, such as the firmware version, the serial number of the token, +the *TouchPolicy* and *PinPolicy*. Note that you may decide to overwrite the builtin CA by a one of your own, +possibly signed by a CA of your company. This would ensure not only that the SSH key is provided by the device, +but also that the device has been provided by your company. + +Please refer to +the `Yubico PIV attestation page `_ and +the `Yubico PIV tool page `_ +for more information. + +Without a policy +================ + +If you want to support PIV keys without making those mandatory, you don't have anything to do: +those keys are just regular RSA/ECDSA keys and they *just work* with The Bastion. +In that case, after having properly configured your hardware token with a key in slot 9a, +you can just use :doc:`/plugins/open/selfAddIngressKey` to add the key to your bastion account, and call it a day. +As a quick guidance, on a Yubikey you can usually generate a key in the proper slot this way, +after you've setup a management key: + +.. code-block:: shell + :emphasize-lines: 1 + + yubico-piv-tool --key=YOUR_MGMT_KEY --action generate --pin-policy always --touch-policy never --slot 9a -o - + +Now, if you want the bastion to be aware that this key is from a hardware token, you shall use the ``--piv`` option +to :doc:`/plugins/open/selfAddIngressKey`. This won't do anything special per-se, except storing +the certificates information, and showing the details of the PIV key in command outputs +such as :doc:`/plugins/open/selfListIngressKeys`. +Note however that if in the future you enable the PIV enforcing policy either on your account or globally, +this key will be considered valid, contrary to all the keys added without the ``--piv`` option, +even if these keys happen to be PIV ones. To add a key with the ``--piv`` option, you'll need the SSH public key +as usual, but also the attestation certificate and the key certificate. +Step by step details on how to get those are out of the scope of this document, +but again as a quick guidance, on a Yubikey you can usually get those this way: + +.. code-block:: shell + :emphasize-lines: 1,2,3 + + yubico-piv-tool --action=read-certificate --slot=9a --key-format=SSH + yubico-piv-tool --action=attest --slot=9a + yubico-piv-tool --action=read-certificate --slot=f9 + +When you'll have added your key, you'll see a few more details than usual: + +.. code-block:: console + :emphasize-lines: 1 + + bssh --osh selfAddIngressKey --piv + Enter PIN for 'PIV Card Holder pin (PIV_II)': + ---the-bastion.example.org--------------------------------the-bastion-3.01.03--- + => add a new public key to your account + -------------------------------------------------------------------------------- + ~ Please paste the SSH key you want to add. This bastion supports the following algorithms: + ~ ED25519: strongness[#####] speed[#####], use `ssh-keygen -t ed25519' to generate one + ~ ECDSA : strongness[####.] speed[#####], use `ssh-keygen -t ecdsa -b 521' to generate one + ~ RSA : strongness[###..] speed[#....], use `ssh-keygen -t rsa -b 4096' to generate one + ~ + ~ In any case, don't save it without a passphrase. + ~ You can prepend your key with a from="IP1,IP2,..." as this bastion policy allows ingress keys "from" override by users + ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCyAMtxGT/RvzBZXiYlrCswZMruRtoBtONrVJTZ3Cj5ZpjaZyCRjQ/ETzZXXbvu9KiBsZyhVb/5H9F7CSGi+D5BlcRAKrT9P8MsT7BHWU14GhJddhHDy4rMnXapE93oxbnQIjQT34ozvTKlb0qOoR/SlT14LllvQS6ajaXB7Fm4bAJG/gYGXHEs2nmZn37Rll6vvpZ4ExM29UrqU3hAjYO0Ha+kL5G8Tr+fOhV/5ZmzNsYigdW7Ft7Co4Tpld9D0PqVhDPK7F1zHIFUXunFsewGtB3IQxLdLGDaCMzrRi11V6q/pBzN/75YsW6npRdOzJKjnwxG19lTtVCmCY3EPRFz + ~ + ~ You have requested to add a PIV-enabled SSH key. + ~ Please paste the PIV attestation certificate of your hardware key in PEM format. + ~ This snippet should start with '-----BEGIN CERTIFICATE-----' and end with '-----END CERTIFICATE-----': + ~ + -----BEGIN CERTIFICATE----- + MIIDIDCCAgigAwIBAgIQAajpKeFbM+X1Yfk8GaH9dzANBgkqhkiG9w0BAQsFADAh + MR8wHQYDVQQDDBZZdWJpY28gUElWIEF0dGVzdGF0aW9uMCAXDTE2MDMxNDAwMDAw + MFoYDzIwNTIwNDE3MDAwMDAwWjAlMSMwIQYDVQQDDBpZdWJpS2V5IFBJViBBdHRl + c3RhdGlvbiA5YTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBALIAy3EZ + P9G/MFleJiWsKzBkyu5G2gG042tUlNncKPlmmNpnIJGND8RPNlddu+70qIGxnKFV + v/kf0XsJIaL4PkGVxEAqtP0/wyxPsEdZTXgaEl12EcPLisyddqkT3ejFudAiNBPf + ijO9MqVvSo6hH9KVPXguWW9BLpqNpcHsWbhsAkb+BgZccSzaeZmfftGWXq++lngT + Ezb1SupTeECNg7Qdr6QvkbxOv586FX/lmbM2xiKB1bsW3sKjhOmV30PQ+pWEM8rs + XXMcgVRe6cWx7Aa0HchDEt0sYNoIzOtGLXVXqr+kHM3/vlixbqelF07MkqOfDEbX + 2VO1UKYJjcQ9EXMCAwEAAaNOMEwwEQYKKwYBBAGCxAoDAwQDBQIEMBQGCisGAQQB + gsQKAwcEBgIEALeG1jAQBgorBgEEAYLECgMIBAIDATAPBgorBgEEAYLECgMJBAEB + MA0GCSqGSIb3DQEBCwUAA4IBAQAq9O6H02KRvSmBYsz23r6cNTNS/fr5lSPYMHz/ + fX+D5B1thKKGstsfZVzoopwIjj86cIWpCYuNfEje+a5HrELL8ClV88JutJR2Nihs + NxU3BbsSUqnwi2rQHcmtHJcC8rjfDzpYDlW1yR+SxVenbVxuRy0v8sbleHSPYaXG + EhjupEAuhq7n0TjZMF1X7KElx9FZZM9HeuxUJvzV7XWiUgA4Zm05+4/zKW01n2kt + +aMaQk7T1oiE0oOK51wJX6J80GzF51pM00oPlh4iDvnnNXYN2KvkNuNwPoceDDE/ + 8K23ZfJyTN5nibk13UbxEWSHMUue1zcnFp0KdhqxbJYSS/9q + -----END CERTIFICATE----- + ~ + ~ Thanks, now please paste the PIV key certificate of your generated key in PEM format. + ~ This snippet should also start with '-----BEGIN CERTIFICATE-----' and end with '-----END CERTIFICATE-----': + ~ + -----BEGIN CERTIFICATE----- + MIIC5jCCAc6gAwIBAgIJAKT/dqaxohbiMA0GCSqGSIb3DQEBCwUAMCsxKTAnBgNV + BAMMIFl1YmljbyBQSVYgUm9vdCBDQSBTZXJpYWwgMjYzNzUxMCAXDTE2MDMxNDAw + MDAwMFoYDzIwNTIwNDE3MDAwMDAwWjAhMR8wHQYDVQQDDBZZdWJpY28gUElWIEF0 + dGVzdGF0aW9uMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwDhP3YUI + yLWSjseIKNzMscqCdicslrdkxPgMoK8Ocxu0err4yvFXiSZZL32BTZYLD8N7Y+d1 + cww6VVsFYdwn01Kc6YLrwM5FIN/msXkGTPdPVhVeqNMHh4QyYrYixwWaTbDCGoQD + axVlifVmPS02Mvm8NDjC17X3LhsV1OiS/wOScsI8HHGgQXQIQEDMnt6cwZ83QK73 + 7Wuu5uhSzT3jVOz28Rnij1p/8PcVWcGKWCPVYNbCmCdcm/sQeJB8y5aERDaePIIZ + v9axnDT0DnUO7aDpzXA7i7XPbrkiSBEp7RCqXGs5cBqGCbq//xGh+/AGtCCV/sQM + nTjl0d2k2Q8XTwIDAQABoxUwEzARBgorBgEEAYLECgMDBAMFAgQwDQYJKoZIhvcN + AQELBQADggEBAHCnp3k5kQaBwYmR9nUHKGY1dgCvhJUlX2SAyY2fUeaMuURcRRlW + BFw6CvLAjvSs5Dy3O6JWDmk+1WFZo0UMr15WZFiS5Fpy0M+GWvBCRP3YmbSw+J2t + kyWypCIIu7cMtLpRYkL5SAlWmUCAz8dZPk5FLPpeqmxgQnRoSSe67IXiv3bNyPA1 + 3NoXI2xw0hWQU1+85tfTxoTxOiAzY8UpAT2GggtSmCwO3sHsHJUYXRyCf8e6jtJL + OFBx/uz+VJoRH7hUVOY+sbP5JJ83dRrWZkS57Hf3q0LOtbn27vM+fmL0y7z4vgDo + DedmrmsbPtsRc3t7RWoqCa80Iq1jPvdm5gw= + -----END CERTIFICATE----- + ~ + ~ Public key successfully added: + ~ info: ADDED_BY=jdoe USING=selfAddIngressKey UNIQID=2993de2bb014 TIMESTAMP=1609427402 DATETIME=2020-12-31T15:10:02 VERSION=3.01.03 + ~ PIV: TouchPolicy=Never, PinPolicy=Always, SerialNo=12345678, Firmware=5.2.4 + ~ fingerprint: SHA256:8B0T6174KUPL1iTSyC0UpnDOvuaCgyKpu8zo9rb2lco (RSA-2048) [2020/12/17] + ------------------------------------------------------------ + +As you can see, we added the public key as usual but were also asked for the two certificates. +On the bastion answer, right before the fingerprint of the key, we have a line starting with *PIV:*, +with some metadata extracted from the certificate. + +Per-account policy +================== + +If you want to force several accounts to only use certified PIV keys, you can set the option per-account +using the :doc:`/plugins/restricted/accountPIV` command, see its documentation page for all the possible options. +The main takeaways are: + +- If you want an account to only have PIV keys, set the ``enforce`` policy for this account +- If you want an account to never require PIV keys, even if the global policy would require it, + set the ``never`` policy (useful for accounts used by automated workflows) + +Global policy +============= + +If you want to apply a policy bastion-wide, please refer to the :ref:`ingressRequirePIV` option. +This policy can still be overridden per-account if needed, see above. + +Temporary grace period +====================== + +If you enable the PIV policy globally or on several accounts, you'll soon find out that sometimes people forget +or lose their PIV-enabled hardware tokens, effectively locking them out of the bastion. +There is a *temporary grace period* feature you can use to handle such cases nicely: + +.. code-block:: console + :emphasize-lines: 1 + + bssh --osh accountPIV --account lechuck --policy grace --ttl 48h + ---the-bastion.example.org--------------------------------the-bastion-3.01.03--- + => modify the PIV policy of an account + -------------------------------------------------------------------------------- + ~ Changing account configuration... + + ~ PIV grace up to 2d+00:00:00 (Wed 2021-01-13 09:22:29 UTC) has been set for this account + ~ Applying change to keys... + + ~ Non-PIV account's ingress keys, if any, have been restored + ------------------------------------------------------------------- + +What happens here is that, for a duration of 48 hours, this account will behave as if no PIV policy was enforced: +non-PIV keys are allowed again. If this account had non-PIV keys before its policy was set to enforce, +those keys are even restored (can be viewed using :doc:`/plugins/open/selfListIngressKeys` as usual), +so that they can easily connect again. However, after the grace period expires, their policy will go back to +what it was previously, and all the non-PIV keys will be disabled again. +This event is logged, so you can easily link this event from your SIEM to a potential ticket to your Helpdesk +for a hardware key replacement, or such. + +This mechanism allows some flexibility (avoiding sending people back home just because they forgot their hardware key), +while still enforcing a high-level security policy with the proper processes in place. diff --git a/_sources/using/sftp_scp_rsync.rst.txt b/_sources/using/sftp_scp_rsync.rst.txt new file mode 100644 index 0000000..cef9736 --- /dev/null +++ b/_sources/using/sftp_scp_rsync.rst.txt @@ -0,0 +1,114 @@ +========================= +SFTP, SCP & RSYNC support +========================= + +.. contents:: + +Introduction +============ + +The Bastion's main goal is to secure ``ssh`` connections. +However, one might also want to use ``sftp``, ``scp`` or ``rsync`` through it. + +Its use is supported through the :doc:`/plugins/open/scp`, :doc:`/plugins/open/sftp` and +:doc:`/plugins/open/rsync` bastion plugins, and documented as part of all the plugins. +This additional documentation section gives some examples and outlines some common configuration errors. + +Prerequisites +============= + +SFTP & SCP +---------- + +The use of SFTP or SCP through the bastion requires an SFTP or SCP program that supports the **-S** option, +and a shell to run the wrapper. This is the case on all operating systems using OpenSSH such as Linux or \*BSD. + +If you're running under Microsoft Windows, you might want to setup either a Linux VM, or a WSL (Windows Subsystem +for Linux) environment, to have the OpenSSH version of ``scp`` or ``sftp`` and a working POSIX-style shell. + +Note that it won't work with Windows GUI apps, because there's no way to specify a wrapper (through **-S**), +and no shell. For example, it won't work under WinSCP. + +RSYNC +----- + +The use of RSYNC through the bastion only requires rsync to be installed locally and remotely, as is the +case for usage without the bastion. + +Basic usage +=========== + +Please check the :doc:`/plugins/open/scp`, :doc:`/plugins/open/sftp` and :doc:`/plugins/open/rsync` +documentation to see how to use these. + +Access model +============ + +.. note:: + + Currently, to be able to use SFTP, SCP or RSYNC with a remote server, + you first need to have a declared SSH access to it. + This might change in a future version. + +Error message 1 +--------------- + +This is briefly explained in the :doc:`/plugins/open/scp`/doc:`/plugins/open/sftp`/:doc:`/plugins/open/rsync` +documentation, but having access rights to SSH to a machine is not enough to have the right to SCP to or from it, +or use SFTP/RSYNC on it. +If you have the following error, then this is the problem you're having: + +:: + + Sorry, you seem to have access through ssh and through scp but by different and distinct means (distinct keys). + The intersection between your rights for ssh and for scp needs to be at least one. + +When this happens, it means that you have at least one declared SSH access to this machine (through one or +several groups, or through personal accesses). You also have at least one declared SCP/SFTP/RSYNC access to it. +However **both accesses are declared through different means**, and more precisely different SSH keys. For example: + +- You are a member of a group having this machine on one hand, and you have a declared SCP/SFTP/RSYNC access to this machine + using a personal access on the other hand. For SSH, the group key would be used, but for SCP/SFTP, your personal key + would be used. However, for technical reasons (that might be lifted in a future version), your SSH and SCP/SFTP/RSYNC access + must be declared with the same key, so in other words, using the same access mean (same group, or personal access). + +- You are a member of group **A** having this machine, but SCP/SFTP/RSYNC access is declared in group **B**. + In that case, as previously, as two different keys are used, this won't work. + +To declare an SCP/SFTP/RSYNC access, in addition to a preexisting SSH access, you should use either: + +- :doc:`/plugins/group-aclkeeper/groupAddServer`, if the SSH access is part of a group + +- :doc:`/plugins/restricted/selfAddPersonalAccess` or :doc:`/plugins/restricted/accountAddPersonalAccess`, + if the SSH access is personal (tied to an account) + +In both cases, where you would use the ``--user`` option to the command, to specify the remote user to use for +the SSH access being declared, you should replace it by either ``--protocol scpdown``, ``--protocol scpup``, +``--protocol sftp`` or ``--protocol rsync``, +to specify that you're about to add an SCP/SFTP/RSYNC access (and not a bare SSH one), and which direction you want +to allow in the case of SCP. + +For SCP, you can allow both directions by using the command first with ``--protocol scpdown``, +then with ``--protocol scpup``. +Note that for SFTP and RYSNC, you can't specify a direction, due to how these protocols work: you either have +SFTP/RSYNC access (hence being able to upload and download files), or you don't. + +For example, this is a valid command to add SFTP access to a machine which is part of a group: + +:: + + bssh --osh groupAddServer --group mygroup --host scpserver.example.org --port 22 --protocol sftp + +Error message 2 +--------------- + +If you have the following message: + +:: + + Sorry, but you don't seem to have access to HOST:IP + +Then it means that you don't even have SSH access to this machine. In that case, somebody should grant you access, +either by adding you to a group having this machine (:doc:`/plugins/group-gatekeeper/groupAddMember`) or by adding +this machine to your personal accesses (:doc:`/plugins/restricted/accountAddPersonalAccess` or +:doc:`/plugins/restricted/selfAddPersonalAccess`). diff --git a/_sources/using/specific_ssh_clients_tutorials/index.rst.txt b/_sources/using/specific_ssh_clients_tutorials/index.rst.txt new file mode 100644 index 0000000..c493cb4 --- /dev/null +++ b/_sources/using/specific_ssh_clients_tutorials/index.rst.txt @@ -0,0 +1,11 @@ +============================== +Specific SSH clients tutorials +============================== + +This section has a few howtos about using The Bastion with some specific SSH clients, +mostly ones having a GUI, as the rest of the documentation assumes usage of the +more widespread SSH CLI. + +.. toctree:: + + putty diff --git a/_sources/using/specific_ssh_clients_tutorials/putty.rst.txt b/_sources/using/specific_ssh_clients_tutorials/putty.rst.txt new file mode 100644 index 0000000..e7b2d82 --- /dev/null +++ b/_sources/using/specific_ssh_clients_tutorials/putty.rst.txt @@ -0,0 +1,77 @@ +Using PuTTY with The Bastion +============================ + +First, you'll need to generate a pair of SSH keys. To this end, use the ``PuTTY`` companion tool: ``PuTTYgen``. + +Before hitting *Generate* to generate a new key pair, ensure that EdDSA is selected, with the Ed25519 curve. +You'll have to move your mouse a bit to feed the pseudo-random number generator. + +.. image:: putty1.png + :alt: Main window of PuTTYgen + +Once the key has been generated, you'll have to input a passphrase that will protect your key. +Ensure this passphrase is sufficiently hard to guess, but ensure you'll not forget it! +Once you've entered your passphrase twice, it should look like this: + +.. image:: putty2.png + :alt: Main window of PuTTYgen once a key has been generated + +You can now hit *Save private key* and choose a file name. +Also save the corresponding public key next to it by hitting *Save public key*, +but don't close ``PuTTYgen`` yet. + +The public key you've just saved, which is also displayed at the top of the ``PuTTYgen`` window, +starting by ``ssd-ed25519 AAAA...`` is the public key you'll need to give to The Bastion when +creating your account there, so you can copy/paste it when The Bastion asks you for a key: + +.. image:: putty3.png + :alt: Creating an account on The Bastion + +Now, you can close ``PuTTYgen`` (as you've saved the private and public keys in their respective +files, you'll be able to use them later), and open ``PuTTY`` itself: + +.. image:: putty4.png + :alt: Main window of PuTTY + +To create the proper connection settings, set your bastion host name (or IP) and port in the +window above, and leave the connection type to SSH. + +Then, navigate to *Connection > SSH > Auth > Credentials*, and use *Browse...* to set the +location of the private key you've generated with ``PuTTYgen``. Ensure you use the private +key, not the public key: the private key usually ends in :file:`.ppk`, as shown below: + +.. image:: putty5.png + :alt: Credentials options section of PuTTY window + +Then, navigate back to *Session*, and save the session settings under any name you wish, +so that the next time you open ``PuTTY``, you'll be able to load these settings back: + +.. image:: putty6.png + :alt: Saving the settings in PuTTY + +Then, you can click *Open* to establish the connection. On the first connection attempt, you'll +be prompted with this dialog box: + +.. image:: putty7.png + :alt: Unknown hostkey dialog box + +This is because ``PuTTY`` never connected to the bastion before, and asks you to verify the +bastion's host public key. This is expected on the first connection, so you can click *Accept*. + +You'll then be prompted for your login, which is the account name you've created on the bastion, +associated with your public key: + +.. image:: putty8.png + :alt: Waiting for the user login + +You'll then need to type the passphrase protecting your private key, so ``PuTTY`` can use it: + +.. image:: putty9.png + :alt: Waiting for the private key passphrase + +Once done, the bastion should authenticate you, and drop you in interactive mode: + +.. image:: putty10.png + :alt: + +You can now use The Bastion! diff --git a/_static/basic.css b/_static/basic.css new file mode 100644 index 0000000..603f6a8 --- /dev/null +++ b/_static/basic.css @@ -0,0 +1,905 @@ +/* + * basic.css + * ~~~~~~~~~ + * + * Sphinx stylesheet -- basic theme. + * + * :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.clearer { + clear: both; +} + +div.section::after { + display: block; + content: ''; + clear: left; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; + word-wrap: break-word; + overflow-wrap : break-word; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +div.sphinxsidebar #searchbox form.search { + overflow: hidden; +} + +div.sphinxsidebar #searchbox input[type="text"] { + float: left; + width: 80%; + padding: 0.25em; + box-sizing: border-box; +} + +div.sphinxsidebar #searchbox input[type="submit"] { + float: left; + width: 20%; + border-left: none; + padding: 0.25em; + box-sizing: border-box; +} + + +img { + border: 0; + max-width: 100%; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li p.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; + margin-left: auto; + margin-right: auto; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable { + width: 100%; +} + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable ul { + margin-top: 0; + margin-bottom: 0; + list-style-type: none; +} + +table.indextable > tbody > tr > td > ul { + padding-left: 0em; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +div.modindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +div.genindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +/* -- domain module index --------------------------------------------------- */ + +table.modindextable td { + padding: 2px; + border-collapse: collapse; +} + +/* -- general body styles --------------------------------------------------- */ + +div.body { + min-width: 450px; + max-width: 800px; +} + +div.body p, div.body dd, div.body li, div.body blockquote { + -moz-hyphens: auto; + -ms-hyphens: auto; + -webkit-hyphens: auto; + hyphens: auto; +} + +a.headerlink { + visibility: hidden; +} + +a.brackets:before, +span.brackets > a:before{ + content: "["; +} + +a.brackets:after, +span.brackets > a:after { + content: "]"; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink, +caption:hover > a.headerlink, +p.caption:hover > a.headerlink, +div.code-block-caption:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +img.align-left, figure.align-left, .figure.align-left, object.align-left { + clear: left; + float: left; + margin-right: 1em; +} + +img.align-right, figure.align-right, .figure.align-right, object.align-right { + clear: right; + float: right; + margin-left: 1em; +} + +img.align-center, figure.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +img.align-default, figure.align-default, .figure.align-default { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left; +} + +.align-center { + text-align: center; +} + +.align-default { + text-align: center; +} + +.align-right { + text-align: right; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar, +aside.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px; + background-color: #ffe; + width: 40%; + float: right; + clear: right; + overflow-x: auto; +} + +p.sidebar-title { + font-weight: bold; +} + +div.admonition, div.topic, blockquote { + clear: left; +} + +/* -- topics ---------------------------------------------------------------- */ + +div.topic { + border: 1px solid #ccc; + padding: 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- content of sidebars/topics/admonitions -------------------------------- */ + +div.sidebar > :last-child, +aside.sidebar > :last-child, +div.topic > :last-child, +div.admonition > :last-child { + margin-bottom: 0; +} + +div.sidebar::after, +aside.sidebar::after, +div.topic::after, +div.admonition::after, +blockquote::after { + display: block; + content: ''; + clear: both; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + margin-top: 10px; + margin-bottom: 10px; + border: 0; + border-collapse: collapse; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +table.align-default { + margin-left: auto; + margin-right: auto; +} + +table caption span.caption-number { + font-style: italic; +} + +table caption span.caption-text { +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 5px; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +table.footnote td, table.footnote th { + border: 0 !important; +} + +th { + text-align: left; + padding-right: 5px; +} + +table.citation { + border-left: solid 1px gray; + margin-left: 1px; +} + +table.citation td { + border-bottom: none; +} + +th > :first-child, +td > :first-child { + margin-top: 0px; +} + +th > :last-child, +td > :last-child { + margin-bottom: 0px; +} + +/* -- figures --------------------------------------------------------------- */ + +div.figure, figure { + margin: 0.5em; + padding: 0.5em; +} + +div.figure p.caption, figcaption { + padding: 0.3em; +} + +div.figure p.caption span.caption-number, +figcaption span.caption-number { + font-style: italic; +} + +div.figure p.caption span.caption-text, +figcaption span.caption-text { +} + +/* -- field list styles ----------------------------------------------------- */ + +table.field-list td, table.field-list th { + border: 0 !important; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +.field-name { + -moz-hyphens: manual; + -ms-hyphens: manual; + -webkit-hyphens: manual; + hyphens: manual; +} + +/* -- hlist styles ---------------------------------------------------------- */ + +table.hlist { + margin: 1em 0; +} + +table.hlist td { + vertical-align: top; +} + +/* -- object description styles --------------------------------------------- */ + +.sig { + font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace; +} + +.sig-name, code.descname { + background-color: transparent; + font-weight: bold; +} + +.sig-name { + font-size: 1.1em; +} + +code.descname { + font-size: 1.2em; +} + +.sig-prename, code.descclassname { + background-color: transparent; +} + +.optional { + font-size: 1.3em; +} + +.sig-paren { + font-size: larger; +} + +.sig-param.n { + font-style: italic; +} + +/* C++ specific styling */ + +.sig-inline.c-texpr, +.sig-inline.cpp-texpr { + font-family: unset; +} + +.sig.c .k, .sig.c .kt, +.sig.cpp .k, .sig.cpp .kt { + color: #0033B3; +} + +.sig.c .m, +.sig.cpp .m { + color: #1750EB; +} + +.sig.c .s, .sig.c .sc, +.sig.cpp .s, .sig.cpp .sc { + color: #067D17; +} + + +/* -- other body styles ----------------------------------------------------- */ + +ol.arabic { + list-style: decimal; +} + +ol.loweralpha { + list-style: lower-alpha; +} + +ol.upperalpha { + list-style: upper-alpha; +} + +ol.lowerroman { + list-style: lower-roman; +} + +ol.upperroman { + list-style: upper-roman; +} + +:not(li) > ol > li:first-child > :first-child, +:not(li) > ul > li:first-child > :first-child { + margin-top: 0px; +} + +:not(li) > ol > li:last-child > :last-child, +:not(li) > ul > li:last-child > :last-child { + margin-bottom: 0px; +} + +ol.simple ol p, +ol.simple ul p, +ul.simple ol p, +ul.simple ul p { + margin-top: 0; +} + +ol.simple > li:not(:first-child) > p, +ul.simple > li:not(:first-child) > p { + margin-top: 0; +} + +ol.simple p, +ul.simple p { + margin-bottom: 0; +} + +dl.footnote > dt, +dl.citation > dt { + float: left; + margin-right: 0.5em; +} + +dl.footnote > dd, +dl.citation > dd { + margin-bottom: 0em; +} + +dl.footnote > dd:after, +dl.citation > dd:after { + content: ""; + clear: both; +} + +dl.field-list { + display: grid; + grid-template-columns: fit-content(30%) auto; +} + +dl.field-list > dt { + font-weight: bold; + word-break: break-word; + padding-left: 0.5em; + padding-right: 5px; +} + +dl.field-list > dt:after { + content: ":"; +} + +dl.field-list > dd { + padding-left: 0.5em; + margin-top: 0em; + margin-left: 0em; + margin-bottom: 0em; +} + +dl { + margin-bottom: 15px; +} + +dd > :first-child { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +dl > dd:last-child, +dl > dd:last-child > :last-child { + margin-bottom: 0; +} + +dt:target, span.highlighted { + background-color: #fbe54e; +} + +rect.highlighted { + fill: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa; +} + +.line-block { + display: block; + margin-top: 1em; + margin-bottom: 1em; +} + +.line-block .line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 1.5em; +} + +.guilabel, .menuselection { + font-family: sans-serif; +} + +.accelerator { + text-decoration: underline; +} + +.classifier { + font-style: oblique; +} + +.classifier:before { + font-style: normal; + margin: 0 0.5em; + content: ":"; + display: inline-block; +} + +abbr, acronym { + border-bottom: dotted 1px; + cursor: help; +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; + overflow-y: hidden; /* fixes display issues on Chrome browsers */ +} + +pre, div[class*="highlight-"] { + clear: both; +} + +span.pre { + -moz-hyphens: none; + -ms-hyphens: none; + -webkit-hyphens: none; + hyphens: none; +} + +div[class*="highlight-"] { + margin: 1em 0; +} + +td.linenos pre { + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + display: block; +} + +table.highlighttable tbody { + display: block; +} + +table.highlighttable tr { + display: flex; +} + +table.highlighttable td { + margin: 0; + padding: 0; +} + +table.highlighttable td.linenos { + padding-right: 0.5em; +} + +table.highlighttable td.code { + flex: 1; + overflow: hidden; +} + +.highlight .hll { + display: block; +} + +div.highlight pre, +table.highlighttable pre { + margin: 0; +} + +div.code-block-caption + div { + margin-top: 0; +} + +div.code-block-caption { + margin-top: 1em; + padding: 2px 5px; + font-size: small; +} + +div.code-block-caption code { + background-color: transparent; +} + +table.highlighttable td.linenos, +span.linenos, +div.highlight span.gp { /* gp: Generic.Prompt */ + user-select: none; + -webkit-user-select: text; /* Safari fallback only */ + -webkit-user-select: none; /* Chrome/Safari */ + -moz-user-select: none; /* Firefox */ + -ms-user-select: none; /* IE10+ */ +} + +div.code-block-caption span.caption-number { + padding: 0.1em 0.3em; + font-style: italic; +} + +div.code-block-caption span.caption-text { +} + +div.literal-block-wrapper { + margin: 1em 0; +} + +code.xref, a code { + background-color: transparent; + font-weight: bold; +} + +h1 code, h2 code, h3 code, h4 code, h5 code, h6 code { + background-color: transparent; +} + +.viewcode-link { + float: right; +} + +.viewcode-back { + float: right; + font-family: sans-serif; +} + +div.viewcode-block:target { + margin: -1px -10px; + padding: 0 10px; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +span.eqno a.headerlink { + position: absolute; + z-index: 1; +} + +div.math:hover a.headerlink { + visibility: visible; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0 !important; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +} \ No newline at end of file diff --git a/_static/css/badge_only.css b/_static/css/badge_only.css new file mode 100644 index 0000000..4d15344 --- /dev/null +++ b/_static/css/badge_only.css @@ -0,0 +1 @@ +.fa:before{-webkit-font-smoothing:antialiased}.clearfix{*zoom:1}.clearfix:before,.clearfix:after{display:table;content:""}.clearfix:after{clear:both}@font-face{font-family:FontAwesome;font-style:normal;font-weight:normal;src:url("../fonts/fontawesome-webfont.eot?#iefix") format("embedded-opentype"),url("../fonts/fontawesome-webfont.woff2") format("woff2"),url("../fonts/fontawesome-webfont.woff") format("woff"),url("../fonts/fontawesome-webfont.ttf") format("truetype"),url("../fonts/fontawesome-webfont.svg#FontAwesome") format("svg")}.fa:before{display:inline-block;font-family:FontAwesome;font-style:normal;font-weight:normal;line-height:1;text-decoration:inherit}a .fa{display:inline-block;text-decoration:inherit}li .fa{display:inline-block}li .fa-large:before,li .fa-large:before{width:1.875em}ul.fas{list-style-type:none;margin-left:2em;text-indent:-0.8em}ul.fas li .fa{width:.8em}ul.fas li .fa-large:before,ul.fas li .fa-large:before{vertical-align:baseline}.fa-book:before{content:""}.icon-book:before{content:""}.fa-caret-down:before{content:""}.icon-caret-down:before{content:""}.fa-caret-up:before{content:""}.icon-caret-up:before{content:""}.fa-caret-left:before{content:""}.icon-caret-left:before{content:""}.fa-caret-right:before{content:""}.icon-caret-right:before{content:""}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:"Lato","proxima-nova","Helvetica Neue",Arial,sans-serif;z-index:400}.rst-versions a{color:#2980B9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27AE60}.rst-versions .rst-current-version::after{clear:both;content:"";display:block}.rst-versions .rst-current-version .fa{color:#fcfcfc}.rst-versions .rst-current-version .fa-book{float:left}.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#E74C3C;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#F1C40F;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:gray;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:solid 1px #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge .fa-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book{float:left}.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width: 768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}} diff --git a/_static/css/thebastion.css b/_static/css/thebastion.css new file mode 100644 index 0000000..10cf121 --- /dev/null +++ b/_static/css/thebastion.css @@ -0,0 +1,11 @@ +@import 'theme.css'; + +.cmdusage .last { + font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace; + white-space: nowrap; + font-size: 75%; +} + +.wy-nav-content { + max-width: 1000px; +} diff --git a/_static/css/theme.css b/_static/css/theme.css new file mode 100644 index 0000000..40606a8 --- /dev/null +++ b/_static/css/theme.css @@ -0,0 +1,4 @@ +html{box-sizing:border-box}*,*::after,*::before{box-sizing:inherit}article,aside,details,figcaption,figure,footer,header,hgroup,nav,section{display:block}audio,canvas,video{display:inline-block;*display:inline;*zoom:1}audio:not([controls]){display:none}[hidden]{display:none}*{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}html{font-size:100%;-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%}body{margin:0}a:hover,a:active{outline:0}abbr[title]{border-bottom:1px dotted}b,strong{font-weight:bold}blockquote{margin:0}dfn{font-style:italic}ins{background:#ff9;color:#000;text-decoration:none}mark{background:#ff0;color:#000;font-style:italic;font-weight:bold}pre,code,.rst-content tt,.rst-content code,kbd,samp{font-family:monospace,serif;_font-family:"courier new",monospace;font-size:1em}pre{white-space:pre}q{quotes:none}q:before,q:after{content:"";content:none}small{font-size:85%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sup{top:-0.5em}sub{bottom:-0.25em}ul,ol,dl{margin:0;padding:0;list-style:none;list-style-image:none}li{list-style:none}dd{margin:0}img{border:0;-ms-interpolation-mode:bicubic;vertical-align:middle;max-width:100%}svg:not(:root){overflow:hidden}figure{margin:0}form{margin:0}fieldset{border:0;margin:0;padding:0}label{cursor:pointer}legend{border:0;*margin-left:-7px;padding:0;white-space:normal}button,input,select,textarea{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle}button,input{line-height:normal}button,input[type="button"],input[type="reset"],input[type="submit"]{cursor:pointer;-webkit-appearance:button;*overflow:visible}button[disabled],input[disabled]{cursor:default}input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0;*width:13px;*height:13px}input[type="search"]{-webkit-appearance:textfield;-moz-box-sizing:content-box;-webkit-box-sizing:content-box;box-sizing:content-box}input[type="search"]::-webkit-search-decoration,input[type="search"]::-webkit-search-cancel-button{-webkit-appearance:none}button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}textarea{overflow:auto;vertical-align:top;resize:vertical}table{border-collapse:collapse;border-spacing:0}td{vertical-align:top}.chromeframe{margin:.2em 0;background:#ccc;color:#000;padding:.2em 0}.ir{display:block;border:0;text-indent:-999em;overflow:hidden;background-color:transparent;background-repeat:no-repeat;text-align:left;direction:ltr;*line-height:0}.ir br{display:none}.hidden{display:none !important;visibility:hidden}.visuallyhidden{border:0;clip:rect(0 0 0 0);height:1px;margin:-1px;overflow:hidden;padding:0;position:absolute;width:1px}.visuallyhidden.focusable:active,.visuallyhidden.focusable:focus{clip:auto;height:auto;margin:0;overflow:visible;position:static;width:auto}.invisible{visibility:hidden}.relative{position:relative}big,small{font-size:100%}@media print{html,body,section{background:none !important}*{box-shadow:none !important;text-shadow:none !important;filter:none !important;-ms-filter:none !important}a,a:visited{text-decoration:underline}.ir a:after,a[href^="javascript:"]:after,a[href^="#"]:after{content:""}pre,blockquote{page-break-inside:avoid}thead{display:table-header-group}tr,img{page-break-inside:avoid}img{max-width:100% !important}@page{margin:.5cm}p,h2,.rst-content .toctree-wrapper>p.caption,h3{orphans:3;widows:3}h2,.rst-content .toctree-wrapper>p.caption,h3{page-break-after:avoid}}.fa:before,.wy-menu-vertical li button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.rst-content .admonition-title:before,.rst-content h1 .headerlink:before,.rst-content h2 .headerlink:before,.rst-content h3 .headerlink:before,.rst-content h4 .headerlink:before,.rst-content h5 .headerlink:before,.rst-content h6 .headerlink:before,.rst-content dl dt .headerlink:before,.rst-content p .headerlink:before,.rst-content p.caption .headerlink:before,.rst-content table>caption .headerlink:before,.rst-content .code-block-caption .headerlink:before,.rst-content .eqno .headerlink:before,.rst-content tt.download span:first-child:before,.rst-content code.download span:first-child:before,.icon:before,.wy-dropdown .caret:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-alert,.rst-content .note,.rst-content .attention,.rst-content .caution,.rst-content .danger,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .tip,.rst-content .warning,.rst-content .seealso,.rst-content .admonition-todo,.rst-content .admonition,.btn,input[type="text"],input[type="password"],input[type="email"],input[type="url"],input[type="date"],input[type="month"],input[type="time"],input[type="datetime"],input[type="datetime-local"],input[type="week"],input[type="number"],input[type="search"],input[type="tel"],input[type="color"],select,textarea,.wy-menu-vertical li.on a,.wy-menu-vertical li.current>a,.wy-side-nav-search>a,.wy-side-nav-search .wy-dropdown>a,.wy-nav-top a{-webkit-font-smoothing:antialiased}.clearfix{*zoom:1}.clearfix:before,.clearfix:after{display:table;content:""}.clearfix:after{clear:both}/*! + * Font Awesome 4.7.0 by @davegandy - http://fontawesome.io - @fontawesome + * License - http://fontawesome.io/license (Font: SIL OFL 1.1, CSS: MIT License) + */@font-face{font-family:'FontAwesome';src:url("../fonts/fontawesome-webfont.eot?v=4.7.0");src:url("../fonts/fontawesome-webfont.eot?#iefix&v=4.7.0") format("embedded-opentype"),url("../fonts/fontawesome-webfont.woff2?v=4.7.0") format("woff2"),url("../fonts/fontawesome-webfont.woff?v=4.7.0") format("woff"),url("../fonts/fontawesome-webfont.ttf?v=4.7.0") format("truetype"),url("../fonts/fontawesome-webfont.svg?v=4.7.0#fontawesomeregular") format("svg");font-weight:normal;font-style:normal}.fa,.wy-menu-vertical li button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li.current>a button.toctree-expand,.rst-content .admonition-title,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content dl dt .headerlink,.rst-content p .headerlink,.rst-content p.caption .headerlink,.rst-content table>caption .headerlink,.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content tt.download span:first-child,.rst-content code.download span:first-child,.icon{display:inline-block;font:normal normal normal 14px/1 FontAwesome;font-size:inherit;text-rendering:auto;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}.fa-lg{font-size:1.3333333333em;line-height:.75em;vertical-align:-15%}.fa-2x{font-size:2em}.fa-3x{font-size:3em}.fa-4x{font-size:4em}.fa-5x{font-size:5em}.fa-fw{width:1.2857142857em;text-align:center}.fa-ul{padding-left:0;margin-left:2.1428571429em;list-style-type:none}.fa-ul>li{position:relative}.fa-li{position:absolute;left:-2.1428571429em;width:2.1428571429em;top:.1428571429em;text-align:center}.fa-li.fa-lg{left:-1.8571428571em}.fa-border{padding:.2em .25em .15em;border:solid 0.08em #eee;border-radius:.1em}.fa-pull-left{float:left}.fa-pull-right{float:right}.fa.fa-pull-left,.wy-menu-vertical li button.fa-pull-left.toctree-expand,.wy-menu-vertical li.on a button.fa-pull-left.toctree-expand,.wy-menu-vertical li.current>a button.fa-pull-left.toctree-expand,.rst-content .fa-pull-left.admonition-title,.rst-content h1 .fa-pull-left.headerlink,.rst-content h2 .fa-pull-left.headerlink,.rst-content h3 .fa-pull-left.headerlink,.rst-content h4 .fa-pull-left.headerlink,.rst-content h5 .fa-pull-left.headerlink,.rst-content h6 .fa-pull-left.headerlink,.rst-content dl dt .fa-pull-left.headerlink,.rst-content p .fa-pull-left.headerlink,.rst-content table>caption .fa-pull-left.headerlink,.rst-content .code-block-caption .fa-pull-left.headerlink,.rst-content .eqno .fa-pull-left.headerlink,.rst-content tt.download span.fa-pull-left:first-child,.rst-content code.download span.fa-pull-left:first-child,.fa-pull-left.icon{margin-right:.3em}.fa.fa-pull-right,.wy-menu-vertical li button.fa-pull-right.toctree-expand,.wy-menu-vertical li.on a button.fa-pull-right.toctree-expand,.wy-menu-vertical li.current>a button.fa-pull-right.toctree-expand,.rst-content .fa-pull-right.admonition-title,.rst-content h1 .fa-pull-right.headerlink,.rst-content h2 .fa-pull-right.headerlink,.rst-content h3 .fa-pull-right.headerlink,.rst-content h4 .fa-pull-right.headerlink,.rst-content h5 .fa-pull-right.headerlink,.rst-content h6 .fa-pull-right.headerlink,.rst-content dl dt .fa-pull-right.headerlink,.rst-content p .fa-pull-right.headerlink,.rst-content table>caption .fa-pull-right.headerlink,.rst-content .code-block-caption .fa-pull-right.headerlink,.rst-content .eqno .fa-pull-right.headerlink,.rst-content tt.download span.fa-pull-right:first-child,.rst-content code.download span.fa-pull-right:first-child,.fa-pull-right.icon{margin-left:.3em}.pull-right{float:right}.pull-left{float:left}.fa.pull-left,.wy-menu-vertical li button.pull-left.toctree-expand,.wy-menu-vertical li.on a button.pull-left.toctree-expand,.wy-menu-vertical li.current>a button.pull-left.toctree-expand,.rst-content .pull-left.admonition-title,.rst-content h1 .pull-left.headerlink,.rst-content h2 .pull-left.headerlink,.rst-content h3 .pull-left.headerlink,.rst-content h4 .pull-left.headerlink,.rst-content h5 .pull-left.headerlink,.rst-content h6 .pull-left.headerlink,.rst-content dl dt .pull-left.headerlink,.rst-content p .pull-left.headerlink,.rst-content table>caption .pull-left.headerlink,.rst-content .code-block-caption .pull-left.headerlink,.rst-content .eqno .pull-left.headerlink,.rst-content tt.download span.pull-left:first-child,.rst-content code.download span.pull-left:first-child,.pull-left.icon{margin-right:.3em}.fa.pull-right,.wy-menu-vertical li button.pull-right.toctree-expand,.wy-menu-vertical li.on a button.pull-right.toctree-expand,.wy-menu-vertical li.current>a button.pull-right.toctree-expand,.rst-content .pull-right.admonition-title,.rst-content h1 .pull-right.headerlink,.rst-content h2 .pull-right.headerlink,.rst-content h3 .pull-right.headerlink,.rst-content h4 .pull-right.headerlink,.rst-content h5 .pull-right.headerlink,.rst-content h6 .pull-right.headerlink,.rst-content dl dt .pull-right.headerlink,.rst-content p .pull-right.headerlink,.rst-content table>caption .pull-right.headerlink,.rst-content .code-block-caption .pull-right.headerlink,.rst-content .eqno .pull-right.headerlink,.rst-content tt.download span.pull-right:first-child,.rst-content code.download span.pull-right:first-child,.pull-right.icon{margin-left:.3em}.fa-spin{-webkit-animation:fa-spin 2s infinite linear;animation:fa-spin 2s infinite linear}.fa-pulse{-webkit-animation:fa-spin 1s infinite steps(8);animation:fa-spin 1s infinite steps(8)}@-webkit-keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}100%{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}@keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}100%{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}.fa-rotate-90{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=1)";-webkit-transform:rotate(90deg);-ms-transform:rotate(90deg);transform:rotate(90deg)}.fa-rotate-180{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2)";-webkit-transform:rotate(180deg);-ms-transform:rotate(180deg);transform:rotate(180deg)}.fa-rotate-270{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=3)";-webkit-transform:rotate(270deg);-ms-transform:rotate(270deg);transform:rotate(270deg)}.fa-flip-horizontal{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=0, mirror=1)";-webkit-transform:scale(-1, 1);-ms-transform:scale(-1, 1);transform:scale(-1, 1)}.fa-flip-vertical{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2, mirror=1)";-webkit-transform:scale(1, -1);-ms-transform:scale(1, -1);transform:scale(1, -1)}:root .fa-rotate-90,:root .fa-rotate-180,:root .fa-rotate-270,:root .fa-flip-horizontal,:root .fa-flip-vertical{filter:none}.fa-stack{position:relative;display:inline-block;width:2em;height:2em;line-height:2em;vertical-align:middle}.fa-stack-1x,.fa-stack-2x{position:absolute;left:0;width:100%;text-align:center}.fa-stack-1x{line-height:inherit}.fa-stack-2x{font-size:2em}.fa-inverse{color:#fff}.fa-glass:before{content:""}.fa-music:before{content:""}.fa-search:before,.icon-search:before{content:""}.fa-envelope-o:before{content:""}.fa-heart:before{content:""}.fa-star:before{content:""}.fa-star-o:before{content:""}.fa-user:before{content:""}.fa-film:before{content:""}.fa-th-large:before{content:""}.fa-th:before{content:""}.fa-th-list:before{content:""}.fa-check:before{content:""}.fa-remove:before,.fa-close:before,.fa-times:before{content:""}.fa-search-plus:before{content:""}.fa-search-minus:before{content:""}.fa-power-off:before{content:""}.fa-signal:before{content:""}.fa-gear:before,.fa-cog:before{content:""}.fa-trash-o:before{content:""}.fa-home:before,.icon-home:before{content:""}.fa-file-o:before{content:""}.fa-clock-o:before{content:""}.fa-road:before{content:""}.fa-download:before,.rst-content tt.download span:first-child:before,.rst-content code.download span:first-child:before{content:""}.fa-arrow-circle-o-down:before{content:""}.fa-arrow-circle-o-up:before{content:""}.fa-inbox:before{content:""}.fa-play-circle-o:before{content:""}.fa-rotate-right:before,.fa-repeat:before{content:""}.fa-refresh:before{content:""}.fa-list-alt:before{content:""}.fa-lock:before{content:""}.fa-flag:before{content:""}.fa-headphones:before{content:""}.fa-volume-off:before{content:""}.fa-volume-down:before{content:""}.fa-volume-up:before{content:""}.fa-qrcode:before{content:""}.fa-barcode:before{content:""}.fa-tag:before{content:""}.fa-tags:before{content:""}.fa-book:before,.icon-book:before{content:""}.fa-bookmark:before{content:""}.fa-print:before{content:""}.fa-camera:before{content:""}.fa-font:before{content:""}.fa-bold:before{content:""}.fa-italic:before{content:""}.fa-text-height:before{content:""}.fa-text-width:before{content:""}.fa-align-left:before{content:""}.fa-align-center:before{content:""}.fa-align-right:before{content:""}.fa-align-justify:before{content:""}.fa-list:before{content:""}.fa-dedent:before,.fa-outdent:before{content:""}.fa-indent:before{content:""}.fa-video-camera:before{content:""}.fa-photo:before,.fa-image:before,.fa-picture-o:before{content:""}.fa-pencil:before{content:""}.fa-map-marker:before{content:""}.fa-adjust:before{content:""}.fa-tint:before{content:""}.fa-edit:before,.fa-pencil-square-o:before{content:""}.fa-share-square-o:before{content:""}.fa-check-square-o:before{content:""}.fa-arrows:before{content:""}.fa-step-backward:before{content:""}.fa-fast-backward:before{content:""}.fa-backward:before{content:""}.fa-play:before{content:""}.fa-pause:before{content:""}.fa-stop:before{content:""}.fa-forward:before{content:""}.fa-fast-forward:before{content:""}.fa-step-forward:before{content:""}.fa-eject:before{content:""}.fa-chevron-left:before{content:""}.fa-chevron-right:before{content:""}.fa-plus-circle:before{content:""}.fa-minus-circle:before{content:""}.fa-times-circle:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before{content:""}.fa-check-circle:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before{content:""}.fa-question-circle:before{content:""}.fa-info-circle:before{content:""}.fa-crosshairs:before{content:""}.fa-times-circle-o:before{content:""}.fa-check-circle-o:before{content:""}.fa-ban:before{content:""}.fa-arrow-left:before{content:""}.fa-arrow-right:before{content:""}.fa-arrow-up:before{content:""}.fa-arrow-down:before{content:""}.fa-mail-forward:before,.fa-share:before{content:""}.fa-expand:before{content:""}.fa-compress:before{content:""}.fa-plus:before{content:""}.fa-minus:before{content:""}.fa-asterisk:before{content:""}.fa-exclamation-circle:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.rst-content .admonition-title:before{content:""}.fa-gift:before{content:""}.fa-leaf:before{content:""}.fa-fire:before,.icon-fire:before{content:""}.fa-eye:before{content:""}.fa-eye-slash:before{content:""}.fa-warning:before,.fa-exclamation-triangle:before{content:""}.fa-plane:before{content:""}.fa-calendar:before{content:""}.fa-random:before{content:""}.fa-comment:before{content:""}.fa-magnet:before{content:""}.fa-chevron-up:before{content:""}.fa-chevron-down:before{content:""}.fa-retweet:before{content:""}.fa-shopping-cart:before{content:""}.fa-folder:before{content:""}.fa-folder-open:before{content:""}.fa-arrows-v:before{content:""}.fa-arrows-h:before{content:""}.fa-bar-chart-o:before,.fa-bar-chart:before{content:""}.fa-twitter-square:before{content:""}.fa-facebook-square:before{content:""}.fa-camera-retro:before{content:""}.fa-key:before{content:""}.fa-gears:before,.fa-cogs:before{content:""}.fa-comments:before{content:""}.fa-thumbs-o-up:before{content:""}.fa-thumbs-o-down:before{content:""}.fa-star-half:before{content:""}.fa-heart-o:before{content:""}.fa-sign-out:before{content:""}.fa-linkedin-square:before{content:""}.fa-thumb-tack:before{content:""}.fa-external-link:before{content:""}.fa-sign-in:before{content:""}.fa-trophy:before{content:""}.fa-github-square:before{content:""}.fa-upload:before{content:""}.fa-lemon-o:before{content:""}.fa-phone:before{content:""}.fa-square-o:before{content:""}.fa-bookmark-o:before{content:""}.fa-phone-square:before{content:""}.fa-twitter:before{content:""}.fa-facebook-f:before,.fa-facebook:before{content:""}.fa-github:before,.icon-github:before{content:""}.fa-unlock:before{content:""}.fa-credit-card:before{content:""}.fa-feed:before,.fa-rss:before{content:""}.fa-hdd-o:before{content:""}.fa-bullhorn:before{content:""}.fa-bell:before{content:""}.fa-certificate:before{content:""}.fa-hand-o-right:before{content:""}.fa-hand-o-left:before{content:""}.fa-hand-o-up:before{content:""}.fa-hand-o-down:before{content:""}.fa-arrow-circle-left:before,.icon-circle-arrow-left:before{content:""}.fa-arrow-circle-right:before,.icon-circle-arrow-right:before{content:""}.fa-arrow-circle-up:before{content:""}.fa-arrow-circle-down:before{content:""}.fa-globe:before{content:""}.fa-wrench:before{content:""}.fa-tasks:before{content:""}.fa-filter:before{content:""}.fa-briefcase:before{content:""}.fa-arrows-alt:before{content:""}.fa-group:before,.fa-users:before{content:""}.fa-chain:before,.fa-link:before,.icon-link:before{content:""}.fa-cloud:before{content:""}.fa-flask:before{content:""}.fa-cut:before,.fa-scissors:before{content:""}.fa-copy:before,.fa-files-o:before{content:""}.fa-paperclip:before{content:""}.fa-save:before,.fa-floppy-o:before{content:""}.fa-square:before{content:""}.fa-navicon:before,.fa-reorder:before,.fa-bars:before{content:""}.fa-list-ul:before{content:""}.fa-list-ol:before{content:""}.fa-strikethrough:before{content:""}.fa-underline:before{content:""}.fa-table:before{content:""}.fa-magic:before{content:""}.fa-truck:before{content:""}.fa-pinterest:before{content:""}.fa-pinterest-square:before{content:""}.fa-google-plus-square:before{content:""}.fa-google-plus:before{content:""}.fa-money:before{content:""}.fa-caret-down:before,.wy-dropdown .caret:before,.icon-caret-down:before{content:""}.fa-caret-up:before{content:""}.fa-caret-left:before{content:""}.fa-caret-right:before{content:""}.fa-columns:before{content:""}.fa-unsorted:before,.fa-sort:before{content:""}.fa-sort-down:before,.fa-sort-desc:before{content:""}.fa-sort-up:before,.fa-sort-asc:before{content:""}.fa-envelope:before{content:""}.fa-linkedin:before{content:""}.fa-rotate-left:before,.fa-undo:before{content:""}.fa-legal:before,.fa-gavel:before{content:""}.fa-dashboard:before,.fa-tachometer:before{content:""}.fa-comment-o:before{content:""}.fa-comments-o:before{content:""}.fa-flash:before,.fa-bolt:before{content:""}.fa-sitemap:before{content:""}.fa-umbrella:before{content:""}.fa-paste:before,.fa-clipboard:before{content:""}.fa-lightbulb-o:before{content:""}.fa-exchange:before{content:""}.fa-cloud-download:before{content:""}.fa-cloud-upload:before{content:""}.fa-user-md:before{content:""}.fa-stethoscope:before{content:""}.fa-suitcase:before{content:""}.fa-bell-o:before{content:""}.fa-coffee:before{content:""}.fa-cutlery:before{content:""}.fa-file-text-o:before{content:""}.fa-building-o:before{content:""}.fa-hospital-o:before{content:""}.fa-ambulance:before{content:""}.fa-medkit:before{content:""}.fa-fighter-jet:before{content:""}.fa-beer:before{content:""}.fa-h-square:before{content:""}.fa-plus-square:before{content:""}.fa-angle-double-left:before{content:""}.fa-angle-double-right:before{content:""}.fa-angle-double-up:before{content:""}.fa-angle-double-down:before{content:""}.fa-angle-left:before{content:""}.fa-angle-right:before{content:""}.fa-angle-up:before{content:""}.fa-angle-down:before{content:""}.fa-desktop:before{content:""}.fa-laptop:before{content:""}.fa-tablet:before{content:""}.fa-mobile-phone:before,.fa-mobile:before{content:""}.fa-circle-o:before{content:""}.fa-quote-left:before{content:""}.fa-quote-right:before{content:""}.fa-spinner:before{content:""}.fa-circle:before{content:""}.fa-mail-reply:before,.fa-reply:before{content:""}.fa-github-alt:before{content:""}.fa-folder-o:before{content:""}.fa-folder-open-o:before{content:""}.fa-smile-o:before{content:""}.fa-frown-o:before{content:""}.fa-meh-o:before{content:""}.fa-gamepad:before{content:""}.fa-keyboard-o:before{content:""}.fa-flag-o:before{content:""}.fa-flag-checkered:before{content:""}.fa-terminal:before{content:""}.fa-code:before{content:""}.fa-mail-reply-all:before,.fa-reply-all:before{content:""}.fa-star-half-empty:before,.fa-star-half-full:before,.fa-star-half-o:before{content:""}.fa-location-arrow:before{content:""}.fa-crop:before{content:""}.fa-code-fork:before{content:""}.fa-unlink:before,.fa-chain-broken:before{content:""}.fa-question:before{content:""}.fa-info:before{content:""}.fa-exclamation:before{content:""}.fa-superscript:before{content:""}.fa-subscript:before{content:""}.fa-eraser:before{content:""}.fa-puzzle-piece:before{content:""}.fa-microphone:before{content:""}.fa-microphone-slash:before{content:""}.fa-shield:before{content:""}.fa-calendar-o:before{content:""}.fa-fire-extinguisher:before{content:""}.fa-rocket:before{content:""}.fa-maxcdn:before{content:""}.fa-chevron-circle-left:before{content:""}.fa-chevron-circle-right:before{content:""}.fa-chevron-circle-up:before{content:""}.fa-chevron-circle-down:before{content:""}.fa-html5:before{content:""}.fa-css3:before{content:""}.fa-anchor:before{content:""}.fa-unlock-alt:before{content:""}.fa-bullseye:before{content:""}.fa-ellipsis-h:before{content:""}.fa-ellipsis-v:before{content:""}.fa-rss-square:before{content:""}.fa-play-circle:before{content:""}.fa-ticket:before{content:""}.fa-minus-square:before{content:""}.fa-minus-square-o:before,.wy-menu-vertical li.on a button.toctree-expand:before,.wy-menu-vertical li.current>a button.toctree-expand:before{content:""}.fa-level-up:before{content:""}.fa-level-down:before{content:""}.fa-check-square:before{content:""}.fa-pencil-square:before{content:""}.fa-external-link-square:before{content:""}.fa-share-square:before{content:""}.fa-compass:before{content:""}.fa-toggle-down:before,.fa-caret-square-o-down:before{content:""}.fa-toggle-up:before,.fa-caret-square-o-up:before{content:""}.fa-toggle-right:before,.fa-caret-square-o-right:before{content:""}.fa-euro:before,.fa-eur:before{content:""}.fa-gbp:before{content:""}.fa-dollar:before,.fa-usd:before{content:""}.fa-rupee:before,.fa-inr:before{content:""}.fa-cny:before,.fa-rmb:before,.fa-yen:before,.fa-jpy:before{content:""}.fa-ruble:before,.fa-rouble:before,.fa-rub:before{content:""}.fa-won:before,.fa-krw:before{content:""}.fa-bitcoin:before,.fa-btc:before{content:""}.fa-file:before{content:""}.fa-file-text:before{content:""}.fa-sort-alpha-asc:before{content:""}.fa-sort-alpha-desc:before{content:""}.fa-sort-amount-asc:before{content:""}.fa-sort-amount-desc:before{content:""}.fa-sort-numeric-asc:before{content:""}.fa-sort-numeric-desc:before{content:""}.fa-thumbs-up:before{content:""}.fa-thumbs-down:before{content:""}.fa-youtube-square:before{content:""}.fa-youtube:before{content:""}.fa-xing:before{content:""}.fa-xing-square:before{content:""}.fa-youtube-play:before{content:""}.fa-dropbox:before{content:""}.fa-stack-overflow:before{content:""}.fa-instagram:before{content:""}.fa-flickr:before{content:""}.fa-adn:before{content:""}.fa-bitbucket:before,.icon-bitbucket:before{content:""}.fa-bitbucket-square:before{content:""}.fa-tumblr:before{content:""}.fa-tumblr-square:before{content:""}.fa-long-arrow-down:before{content:""}.fa-long-arrow-up:before{content:""}.fa-long-arrow-left:before{content:""}.fa-long-arrow-right:before{content:""}.fa-apple:before{content:""}.fa-windows:before{content:""}.fa-android:before{content:""}.fa-linux:before{content:""}.fa-dribbble:before{content:""}.fa-skype:before{content:""}.fa-foursquare:before{content:""}.fa-trello:before{content:""}.fa-female:before{content:""}.fa-male:before{content:""}.fa-gittip:before,.fa-gratipay:before{content:""}.fa-sun-o:before{content:""}.fa-moon-o:before{content:""}.fa-archive:before{content:""}.fa-bug:before{content:""}.fa-vk:before{content:""}.fa-weibo:before{content:""}.fa-renren:before{content:""}.fa-pagelines:before{content:""}.fa-stack-exchange:before{content:""}.fa-arrow-circle-o-right:before{content:""}.fa-arrow-circle-o-left:before{content:""}.fa-toggle-left:before,.fa-caret-square-o-left:before{content:""}.fa-dot-circle-o:before{content:""}.fa-wheelchair:before{content:""}.fa-vimeo-square:before{content:""}.fa-turkish-lira:before,.fa-try:before{content:""}.fa-plus-square-o:before,.wy-menu-vertical li button.toctree-expand:before{content:""}.fa-space-shuttle:before{content:""}.fa-slack:before{content:""}.fa-envelope-square:before{content:""}.fa-wordpress:before{content:""}.fa-openid:before{content:""}.fa-institution:before,.fa-bank:before,.fa-university:before{content:""}.fa-mortar-board:before,.fa-graduation-cap:before{content:""}.fa-yahoo:before{content:""}.fa-google:before{content:""}.fa-reddit:before{content:""}.fa-reddit-square:before{content:""}.fa-stumbleupon-circle:before{content:""}.fa-stumbleupon:before{content:""}.fa-delicious:before{content:""}.fa-digg:before{content:""}.fa-pied-piper-pp:before{content:""}.fa-pied-piper-alt:before{content:""}.fa-drupal:before{content:""}.fa-joomla:before{content:""}.fa-language:before{content:""}.fa-fax:before{content:""}.fa-building:before{content:""}.fa-child:before{content:""}.fa-paw:before{content:""}.fa-spoon:before{content:""}.fa-cube:before{content:""}.fa-cubes:before{content:""}.fa-behance:before{content:""}.fa-behance-square:before{content:""}.fa-steam:before{content:""}.fa-steam-square:before{content:""}.fa-recycle:before{content:""}.fa-automobile:before,.fa-car:before{content:""}.fa-cab:before,.fa-taxi:before{content:""}.fa-tree:before{content:""}.fa-spotify:before{content:""}.fa-deviantart:before{content:""}.fa-soundcloud:before{content:""}.fa-database:before{content:""}.fa-file-pdf-o:before{content:""}.fa-file-word-o:before{content:""}.fa-file-excel-o:before{content:""}.fa-file-powerpoint-o:before{content:""}.fa-file-photo-o:before,.fa-file-picture-o:before,.fa-file-image-o:before{content:""}.fa-file-zip-o:before,.fa-file-archive-o:before{content:""}.fa-file-sound-o:before,.fa-file-audio-o:before{content:""}.fa-file-movie-o:before,.fa-file-video-o:before{content:""}.fa-file-code-o:before{content:""}.fa-vine:before{content:""}.fa-codepen:before{content:""}.fa-jsfiddle:before{content:""}.fa-life-bouy:before,.fa-life-buoy:before,.fa-life-saver:before,.fa-support:before,.fa-life-ring:before{content:""}.fa-circle-o-notch:before{content:""}.fa-ra:before,.fa-resistance:before,.fa-rebel:before{content:""}.fa-ge:before,.fa-empire:before{content:""}.fa-git-square:before{content:""}.fa-git:before{content:""}.fa-y-combinator-square:before,.fa-yc-square:before,.fa-hacker-news:before{content:""}.fa-tencent-weibo:before{content:""}.fa-qq:before{content:""}.fa-wechat:before,.fa-weixin:before{content:""}.fa-send:before,.fa-paper-plane:before{content:""}.fa-send-o:before,.fa-paper-plane-o:before{content:""}.fa-history:before{content:""}.fa-circle-thin:before{content:""}.fa-header:before{content:""}.fa-paragraph:before{content:""}.fa-sliders:before{content:""}.fa-share-alt:before{content:""}.fa-share-alt-square:before{content:""}.fa-bomb:before{content:""}.fa-soccer-ball-o:before,.fa-futbol-o:before{content:""}.fa-tty:before{content:""}.fa-binoculars:before{content:""}.fa-plug:before{content:""}.fa-slideshare:before{content:""}.fa-twitch:before{content:""}.fa-yelp:before{content:""}.fa-newspaper-o:before{content:""}.fa-wifi:before{content:""}.fa-calculator:before{content:""}.fa-paypal:before{content:""}.fa-google-wallet:before{content:""}.fa-cc-visa:before{content:""}.fa-cc-mastercard:before{content:""}.fa-cc-discover:before{content:""}.fa-cc-amex:before{content:""}.fa-cc-paypal:before{content:""}.fa-cc-stripe:before{content:""}.fa-bell-slash:before{content:""}.fa-bell-slash-o:before{content:""}.fa-trash:before{content:""}.fa-copyright:before{content:""}.fa-at:before{content:""}.fa-eyedropper:before{content:""}.fa-paint-brush:before{content:""}.fa-birthday-cake:before{content:""}.fa-area-chart:before{content:""}.fa-pie-chart:before{content:""}.fa-line-chart:before{content:""}.fa-lastfm:before{content:""}.fa-lastfm-square:before{content:""}.fa-toggle-off:before{content:""}.fa-toggle-on:before{content:""}.fa-bicycle:before{content:""}.fa-bus:before{content:""}.fa-ioxhost:before{content:""}.fa-angellist:before{content:""}.fa-cc:before{content:""}.fa-shekel:before,.fa-sheqel:before,.fa-ils:before{content:""}.fa-meanpath:before{content:""}.fa-buysellads:before{content:""}.fa-connectdevelop:before{content:""}.fa-dashcube:before{content:""}.fa-forumbee:before{content:""}.fa-leanpub:before{content:""}.fa-sellsy:before{content:""}.fa-shirtsinbulk:before{content:""}.fa-simplybuilt:before{content:""}.fa-skyatlas:before{content:""}.fa-cart-plus:before{content:""}.fa-cart-arrow-down:before{content:""}.fa-diamond:before{content:""}.fa-ship:before{content:""}.fa-user-secret:before{content:""}.fa-motorcycle:before{content:""}.fa-street-view:before{content:""}.fa-heartbeat:before{content:""}.fa-venus:before{content:""}.fa-mars:before{content:""}.fa-mercury:before{content:""}.fa-intersex:before,.fa-transgender:before{content:""}.fa-transgender-alt:before{content:""}.fa-venus-double:before{content:""}.fa-mars-double:before{content:""}.fa-venus-mars:before{content:""}.fa-mars-stroke:before{content:""}.fa-mars-stroke-v:before{content:""}.fa-mars-stroke-h:before{content:""}.fa-neuter:before{content:""}.fa-genderless:before{content:""}.fa-facebook-official:before{content:""}.fa-pinterest-p:before{content:""}.fa-whatsapp:before{content:""}.fa-server:before{content:""}.fa-user-plus:before{content:""}.fa-user-times:before{content:""}.fa-hotel:before,.fa-bed:before{content:""}.fa-viacoin:before{content:""}.fa-train:before{content:""}.fa-subway:before{content:""}.fa-medium:before{content:""}.fa-yc:before,.fa-y-combinator:before{content:""}.fa-optin-monster:before{content:""}.fa-opencart:before{content:""}.fa-expeditedssl:before{content:""}.fa-battery-4:before,.fa-battery:before,.fa-battery-full:before{content:""}.fa-battery-3:before,.fa-battery-three-quarters:before{content:""}.fa-battery-2:before,.fa-battery-half:before{content:""}.fa-battery-1:before,.fa-battery-quarter:before{content:""}.fa-battery-0:before,.fa-battery-empty:before{content:""}.fa-mouse-pointer:before{content:""}.fa-i-cursor:before{content:""}.fa-object-group:before{content:""}.fa-object-ungroup:before{content:""}.fa-sticky-note:before{content:""}.fa-sticky-note-o:before{content:""}.fa-cc-jcb:before{content:""}.fa-cc-diners-club:before{content:""}.fa-clone:before{content:""}.fa-balance-scale:before{content:""}.fa-hourglass-o:before{content:""}.fa-hourglass-1:before,.fa-hourglass-start:before{content:""}.fa-hourglass-2:before,.fa-hourglass-half:before{content:""}.fa-hourglass-3:before,.fa-hourglass-end:before{content:""}.fa-hourglass:before{content:""}.fa-hand-grab-o:before,.fa-hand-rock-o:before{content:""}.fa-hand-stop-o:before,.fa-hand-paper-o:before{content:""}.fa-hand-scissors-o:before{content:""}.fa-hand-lizard-o:before{content:""}.fa-hand-spock-o:before{content:""}.fa-hand-pointer-o:before{content:""}.fa-hand-peace-o:before{content:""}.fa-trademark:before{content:""}.fa-registered:before{content:""}.fa-creative-commons:before{content:""}.fa-gg:before{content:""}.fa-gg-circle:before{content:""}.fa-tripadvisor:before{content:""}.fa-odnoklassniki:before{content:""}.fa-odnoklassniki-square:before{content:""}.fa-get-pocket:before{content:""}.fa-wikipedia-w:before{content:""}.fa-safari:before{content:""}.fa-chrome:before{content:""}.fa-firefox:before{content:""}.fa-opera:before{content:""}.fa-internet-explorer:before{content:""}.fa-tv:before,.fa-television:before{content:""}.fa-contao:before{content:""}.fa-500px:before{content:""}.fa-amazon:before{content:""}.fa-calendar-plus-o:before{content:""}.fa-calendar-minus-o:before{content:""}.fa-calendar-times-o:before{content:""}.fa-calendar-check-o:before{content:""}.fa-industry:before{content:""}.fa-map-pin:before{content:""}.fa-map-signs:before{content:""}.fa-map-o:before{content:""}.fa-map:before{content:""}.fa-commenting:before{content:""}.fa-commenting-o:before{content:""}.fa-houzz:before{content:""}.fa-vimeo:before{content:""}.fa-black-tie:before{content:""}.fa-fonticons:before{content:""}.fa-reddit-alien:before{content:""}.fa-edge:before{content:""}.fa-credit-card-alt:before{content:""}.fa-codiepie:before{content:""}.fa-modx:before{content:""}.fa-fort-awesome:before{content:""}.fa-usb:before{content:""}.fa-product-hunt:before{content:""}.fa-mixcloud:before{content:""}.fa-scribd:before{content:""}.fa-pause-circle:before{content:""}.fa-pause-circle-o:before{content:""}.fa-stop-circle:before{content:""}.fa-stop-circle-o:before{content:""}.fa-shopping-bag:before{content:""}.fa-shopping-basket:before{content:""}.fa-hashtag:before{content:""}.fa-bluetooth:before{content:""}.fa-bluetooth-b:before{content:""}.fa-percent:before{content:""}.fa-gitlab:before,.icon-gitlab:before{content:""}.fa-wpbeginner:before{content:""}.fa-wpforms:before{content:""}.fa-envira:before{content:""}.fa-universal-access:before{content:""}.fa-wheelchair-alt:before{content:""}.fa-question-circle-o:before{content:""}.fa-blind:before{content:""}.fa-audio-description:before{content:""}.fa-volume-control-phone:before{content:""}.fa-braille:before{content:""}.fa-assistive-listening-systems:before{content:""}.fa-asl-interpreting:before,.fa-american-sign-language-interpreting:before{content:""}.fa-deafness:before,.fa-hard-of-hearing:before,.fa-deaf:before{content:""}.fa-glide:before{content:""}.fa-glide-g:before{content:""}.fa-signing:before,.fa-sign-language:before{content:""}.fa-low-vision:before{content:""}.fa-viadeo:before{content:""}.fa-viadeo-square:before{content:""}.fa-snapchat:before{content:""}.fa-snapchat-ghost:before{content:""}.fa-snapchat-square:before{content:""}.fa-pied-piper:before{content:""}.fa-first-order:before{content:""}.fa-yoast:before{content:""}.fa-themeisle:before{content:""}.fa-google-plus-circle:before,.fa-google-plus-official:before{content:""}.fa-fa:before,.fa-font-awesome:before{content:""}.fa-handshake-o:before{content:""}.fa-envelope-open:before{content:""}.fa-envelope-open-o:before{content:""}.fa-linode:before{content:""}.fa-address-book:before{content:""}.fa-address-book-o:before{content:""}.fa-vcard:before,.fa-address-card:before{content:""}.fa-vcard-o:before,.fa-address-card-o:before{content:""}.fa-user-circle:before{content:""}.fa-user-circle-o:before{content:""}.fa-user-o:before{content:""}.fa-id-badge:before{content:""}.fa-drivers-license:before,.fa-id-card:before{content:""}.fa-drivers-license-o:before,.fa-id-card-o:before{content:""}.fa-quora:before{content:""}.fa-free-code-camp:before{content:""}.fa-telegram:before{content:""}.fa-thermometer-4:before,.fa-thermometer:before,.fa-thermometer-full:before{content:""}.fa-thermometer-3:before,.fa-thermometer-three-quarters:before{content:""}.fa-thermometer-2:before,.fa-thermometer-half:before{content:""}.fa-thermometer-1:before,.fa-thermometer-quarter:before{content:""}.fa-thermometer-0:before,.fa-thermometer-empty:before{content:""}.fa-shower:before{content:""}.fa-bathtub:before,.fa-s15:before,.fa-bath:before{content:""}.fa-podcast:before{content:""}.fa-window-maximize:before{content:""}.fa-window-minimize:before{content:""}.fa-window-restore:before{content:""}.fa-times-rectangle:before,.fa-window-close:before{content:""}.fa-times-rectangle-o:before,.fa-window-close-o:before{content:""}.fa-bandcamp:before{content:""}.fa-grav:before{content:""}.fa-etsy:before{content:""}.fa-imdb:before{content:""}.fa-ravelry:before{content:""}.fa-eercast:before{content:""}.fa-microchip:before{content:""}.fa-snowflake-o:before{content:""}.fa-superpowers:before{content:""}.fa-wpexplorer:before{content:""}.fa-meetup:before{content:""}.sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0, 0, 0, 0);border:0}.sr-only-focusable:active,.sr-only-focusable:focus{position:static;width:auto;height:auto;margin:0;overflow:visible;clip:auto}.fa,.wy-menu-vertical li button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li.current>a button.toctree-expand,.rst-content .admonition-title,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content dl dt .headerlink,.rst-content p .headerlink,.rst-content p.caption .headerlink,.rst-content table>caption .headerlink,.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content tt.download span:first-child,.rst-content code.download span:first-child,.icon,.wy-dropdown .caret,.wy-inline-validate.wy-inline-validate-success .wy-input-context,.wy-inline-validate.wy-inline-validate-danger .wy-input-context,.wy-inline-validate.wy-inline-validate-warning .wy-input-context,.wy-inline-validate.wy-inline-validate-info .wy-input-context{font-family:inherit}.fa:before,.wy-menu-vertical li button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.rst-content .admonition-title:before,.rst-content h1 .headerlink:before,.rst-content h2 .headerlink:before,.rst-content h3 .headerlink:before,.rst-content h4 .headerlink:before,.rst-content h5 .headerlink:before,.rst-content h6 .headerlink:before,.rst-content dl dt .headerlink:before,.rst-content p .headerlink:before,.rst-content p.caption .headerlink:before,.rst-content table>caption .headerlink:before,.rst-content .code-block-caption .headerlink:before,.rst-content .eqno .headerlink:before,.rst-content tt.download span:first-child:before,.rst-content code.download span:first-child:before,.icon:before,.wy-dropdown .caret:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before{font-family:"FontAwesome";display:inline-block;font-style:normal;font-weight:normal;line-height:1;text-decoration:inherit}a .fa,a .wy-menu-vertical li button.toctree-expand,.wy-menu-vertical li a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li.current>a button.toctree-expand,a .rst-content .admonition-title,.rst-content a .admonition-title,a .rst-content h1 .headerlink,.rst-content h1 a .headerlink,a .rst-content h2 .headerlink,.rst-content h2 a .headerlink,a .rst-content h3 .headerlink,.rst-content h3 a .headerlink,a .rst-content h4 .headerlink,.rst-content h4 a .headerlink,a .rst-content h5 .headerlink,.rst-content h5 a .headerlink,a .rst-content h6 .headerlink,.rst-content h6 a .headerlink,a .rst-content dl dt .headerlink,.rst-content dl dt a .headerlink,a .rst-content p .headerlink,.rst-content p a .headerlink,a .rst-content p.caption .headerlink,.rst-content p.caption a .headerlink,a .rst-content table>caption .headerlink,.rst-content table>caption a .headerlink,a .rst-content .code-block-caption .headerlink,.rst-content .code-block-caption a .headerlink,a .rst-content .eqno .headerlink,.rst-content .eqno a .headerlink,a .rst-content tt.download span:first-child,.rst-content tt.download a span:first-child,a .rst-content code.download span:first-child,.rst-content code.download a span:first-child,a .icon{display:inline-block;text-decoration:inherit}.btn .fa,.btn .wy-menu-vertical li button.toctree-expand,.wy-menu-vertical li .btn button.toctree-expand,.btn .wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li.on a .btn button.toctree-expand,.btn .wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.current>a .btn button.toctree-expand,.btn .rst-content .admonition-title,.rst-content .btn .admonition-title,.btn .rst-content h1 .headerlink,.rst-content h1 .btn .headerlink,.btn .rst-content h2 .headerlink,.rst-content h2 .btn .headerlink,.btn .rst-content h3 .headerlink,.rst-content h3 .btn .headerlink,.btn .rst-content h4 .headerlink,.rst-content h4 .btn .headerlink,.btn .rst-content h5 .headerlink,.rst-content h5 .btn .headerlink,.btn .rst-content h6 .headerlink,.rst-content h6 .btn .headerlink,.btn .rst-content dl dt .headerlink,.rst-content dl dt .btn .headerlink,.btn .rst-content p .headerlink,.rst-content p .btn .headerlink,.btn .rst-content table>caption .headerlink,.rst-content table>caption .btn .headerlink,.btn .rst-content .code-block-caption .headerlink,.rst-content .code-block-caption .btn .headerlink,.btn .rst-content .eqno .headerlink,.rst-content .eqno .btn .headerlink,.btn .rst-content tt.download span:first-child,.rst-content tt.download .btn span:first-child,.btn .rst-content code.download span:first-child,.rst-content code.download .btn span:first-child,.btn .icon,.nav .fa,.nav .wy-menu-vertical li button.toctree-expand,.wy-menu-vertical li .nav button.toctree-expand,.nav .wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li.on a .nav button.toctree-expand,.nav .wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.current>a .nav button.toctree-expand,.nav .rst-content .admonition-title,.rst-content .nav .admonition-title,.nav .rst-content h1 .headerlink,.rst-content h1 .nav .headerlink,.nav .rst-content h2 .headerlink,.rst-content h2 .nav .headerlink,.nav .rst-content h3 .headerlink,.rst-content h3 .nav .headerlink,.nav .rst-content h4 .headerlink,.rst-content h4 .nav .headerlink,.nav .rst-content h5 .headerlink,.rst-content h5 .nav .headerlink,.nav .rst-content h6 .headerlink,.rst-content h6 .nav .headerlink,.nav .rst-content dl dt .headerlink,.rst-content dl dt .nav .headerlink,.nav .rst-content p .headerlink,.rst-content p .nav .headerlink,.nav .rst-content table>caption .headerlink,.rst-content table>caption .nav .headerlink,.nav .rst-content .code-block-caption .headerlink,.rst-content .code-block-caption .nav .headerlink,.nav .rst-content .eqno .headerlink,.rst-content .eqno .nav .headerlink,.nav .rst-content tt.download span:first-child,.rst-content tt.download .nav span:first-child,.nav .rst-content code.download span:first-child,.rst-content code.download .nav span:first-child,.nav .icon{display:inline}.btn .fa.fa-large,.btn .wy-menu-vertical li button.fa-large.toctree-expand,.wy-menu-vertical li .btn button.fa-large.toctree-expand,.btn .rst-content .fa-large.admonition-title,.rst-content .btn .fa-large.admonition-title,.btn .rst-content h1 .fa-large.headerlink,.rst-content h1 .btn .fa-large.headerlink,.btn .rst-content h2 .fa-large.headerlink,.rst-content h2 .btn .fa-large.headerlink,.btn .rst-content h3 .fa-large.headerlink,.rst-content h3 .btn .fa-large.headerlink,.btn .rst-content h4 .fa-large.headerlink,.rst-content h4 .btn .fa-large.headerlink,.btn .rst-content h5 .fa-large.headerlink,.rst-content h5 .btn .fa-large.headerlink,.btn .rst-content h6 .fa-large.headerlink,.rst-content h6 .btn .fa-large.headerlink,.btn .rst-content dl dt .fa-large.headerlink,.rst-content dl dt .btn .fa-large.headerlink,.btn .rst-content p .fa-large.headerlink,.rst-content p .btn .fa-large.headerlink,.btn .rst-content table>caption .fa-large.headerlink,.rst-content table>caption .btn .fa-large.headerlink,.btn .rst-content .code-block-caption .fa-large.headerlink,.rst-content .code-block-caption .btn .fa-large.headerlink,.btn .rst-content .eqno .fa-large.headerlink,.rst-content .eqno .btn .fa-large.headerlink,.btn .rst-content tt.download span.fa-large:first-child,.rst-content tt.download .btn span.fa-large:first-child,.btn .rst-content code.download span.fa-large:first-child,.rst-content code.download .btn span.fa-large:first-child,.btn .fa-large.icon,.nav .fa.fa-large,.nav .wy-menu-vertical li button.fa-large.toctree-expand,.wy-menu-vertical li .nav button.fa-large.toctree-expand,.nav .rst-content .fa-large.admonition-title,.rst-content .nav .fa-large.admonition-title,.nav .rst-content h1 .fa-large.headerlink,.rst-content h1 .nav .fa-large.headerlink,.nav .rst-content h2 .fa-large.headerlink,.rst-content h2 .nav .fa-large.headerlink,.nav .rst-content h3 .fa-large.headerlink,.rst-content h3 .nav .fa-large.headerlink,.nav .rst-content h4 .fa-large.headerlink,.rst-content h4 .nav .fa-large.headerlink,.nav .rst-content h5 .fa-large.headerlink,.rst-content h5 .nav .fa-large.headerlink,.nav .rst-content h6 .fa-large.headerlink,.rst-content h6 .nav .fa-large.headerlink,.nav .rst-content dl dt .fa-large.headerlink,.rst-content dl dt .nav .fa-large.headerlink,.nav .rst-content p .fa-large.headerlink,.rst-content p .nav .fa-large.headerlink,.nav .rst-content table>caption .fa-large.headerlink,.rst-content table>caption .nav .fa-large.headerlink,.nav .rst-content .code-block-caption .fa-large.headerlink,.rst-content .code-block-caption .nav .fa-large.headerlink,.nav .rst-content .eqno .fa-large.headerlink,.rst-content .eqno .nav .fa-large.headerlink,.nav .rst-content tt.download span.fa-large:first-child,.rst-content tt.download .nav span.fa-large:first-child,.nav .rst-content code.download span.fa-large:first-child,.rst-content code.download .nav span.fa-large:first-child,.nav .fa-large.icon{line-height:.9em}.btn .fa.fa-spin,.btn .wy-menu-vertical li button.fa-spin.toctree-expand,.wy-menu-vertical li .btn button.fa-spin.toctree-expand,.btn .rst-content .fa-spin.admonition-title,.rst-content .btn .fa-spin.admonition-title,.btn .rst-content h1 .fa-spin.headerlink,.rst-content h1 .btn .fa-spin.headerlink,.btn .rst-content h2 .fa-spin.headerlink,.rst-content h2 .btn .fa-spin.headerlink,.btn .rst-content h3 .fa-spin.headerlink,.rst-content h3 .btn .fa-spin.headerlink,.btn .rst-content h4 .fa-spin.headerlink,.rst-content h4 .btn .fa-spin.headerlink,.btn .rst-content h5 .fa-spin.headerlink,.rst-content h5 .btn .fa-spin.headerlink,.btn .rst-content h6 .fa-spin.headerlink,.rst-content h6 .btn .fa-spin.headerlink,.btn .rst-content dl dt .fa-spin.headerlink,.rst-content dl dt .btn .fa-spin.headerlink,.btn .rst-content p .fa-spin.headerlink,.rst-content p .btn .fa-spin.headerlink,.btn .rst-content table>caption .fa-spin.headerlink,.rst-content table>caption .btn .fa-spin.headerlink,.btn .rst-content .code-block-caption .fa-spin.headerlink,.rst-content .code-block-caption .btn .fa-spin.headerlink,.btn .rst-content .eqno .fa-spin.headerlink,.rst-content .eqno .btn .fa-spin.headerlink,.btn .rst-content tt.download span.fa-spin:first-child,.rst-content tt.download .btn span.fa-spin:first-child,.btn .rst-content code.download span.fa-spin:first-child,.rst-content code.download .btn span.fa-spin:first-child,.btn .fa-spin.icon,.nav .fa.fa-spin,.nav .wy-menu-vertical li button.fa-spin.toctree-expand,.wy-menu-vertical li .nav button.fa-spin.toctree-expand,.nav .rst-content .fa-spin.admonition-title,.rst-content .nav .fa-spin.admonition-title,.nav .rst-content h1 .fa-spin.headerlink,.rst-content h1 .nav .fa-spin.headerlink,.nav .rst-content h2 .fa-spin.headerlink,.rst-content h2 .nav .fa-spin.headerlink,.nav .rst-content h3 .fa-spin.headerlink,.rst-content h3 .nav .fa-spin.headerlink,.nav .rst-content h4 .fa-spin.headerlink,.rst-content h4 .nav .fa-spin.headerlink,.nav .rst-content h5 .fa-spin.headerlink,.rst-content h5 .nav .fa-spin.headerlink,.nav .rst-content h6 .fa-spin.headerlink,.rst-content h6 .nav .fa-spin.headerlink,.nav .rst-content dl dt .fa-spin.headerlink,.rst-content dl dt .nav .fa-spin.headerlink,.nav .rst-content p .fa-spin.headerlink,.rst-content p .nav .fa-spin.headerlink,.nav .rst-content table>caption .fa-spin.headerlink,.rst-content table>caption .nav .fa-spin.headerlink,.nav .rst-content .code-block-caption .fa-spin.headerlink,.rst-content .code-block-caption .nav .fa-spin.headerlink,.nav .rst-content .eqno .fa-spin.headerlink,.rst-content .eqno .nav .fa-spin.headerlink,.nav .rst-content tt.download span.fa-spin:first-child,.rst-content tt.download .nav span.fa-spin:first-child,.nav .rst-content code.download span.fa-spin:first-child,.rst-content code.download .nav span.fa-spin:first-child,.nav .fa-spin.icon{display:inline-block}.btn.fa:before,.wy-menu-vertical li button.btn.toctree-expand:before,.rst-content .btn.admonition-title:before,.rst-content h1 .btn.headerlink:before,.rst-content h2 .btn.headerlink:before,.rst-content h3 .btn.headerlink:before,.rst-content h4 .btn.headerlink:before,.rst-content h5 .btn.headerlink:before,.rst-content h6 .btn.headerlink:before,.rst-content dl dt .btn.headerlink:before,.rst-content p .btn.headerlink:before,.rst-content table>caption .btn.headerlink:before,.rst-content .code-block-caption .btn.headerlink:before,.rst-content .eqno .btn.headerlink:before,.rst-content tt.download span.btn:first-child:before,.rst-content code.download span.btn:first-child:before,.btn.icon:before{opacity:.5;-webkit-transition:opacity .05s ease-in;-moz-transition:opacity .05s ease-in;transition:opacity .05s ease-in}.btn.fa:hover:before,.wy-menu-vertical li button.btn.toctree-expand:hover:before,.rst-content .btn.admonition-title:hover:before,.rst-content h1 .btn.headerlink:hover:before,.rst-content h2 .btn.headerlink:hover:before,.rst-content h3 .btn.headerlink:hover:before,.rst-content h4 .btn.headerlink:hover:before,.rst-content h5 .btn.headerlink:hover:before,.rst-content h6 .btn.headerlink:hover:before,.rst-content dl dt .btn.headerlink:hover:before,.rst-content p .btn.headerlink:hover:before,.rst-content table>caption .btn.headerlink:hover:before,.rst-content .code-block-caption .btn.headerlink:hover:before,.rst-content .eqno .btn.headerlink:hover:before,.rst-content tt.download span.btn:first-child:hover:before,.rst-content code.download span.btn:first-child:hover:before,.btn.icon:hover:before{opacity:1}.btn-mini .fa:before,.btn-mini .wy-menu-vertical li button.toctree-expand:before,.wy-menu-vertical li .btn-mini button.toctree-expand:before,.btn-mini .rst-content .admonition-title:before,.rst-content .btn-mini .admonition-title:before,.btn-mini .rst-content h1 .headerlink:before,.rst-content h1 .btn-mini .headerlink:before,.btn-mini .rst-content h2 .headerlink:before,.rst-content h2 .btn-mini .headerlink:before,.btn-mini .rst-content h3 .headerlink:before,.rst-content h3 .btn-mini .headerlink:before,.btn-mini .rst-content h4 .headerlink:before,.rst-content h4 .btn-mini .headerlink:before,.btn-mini .rst-content h5 .headerlink:before,.rst-content h5 .btn-mini .headerlink:before,.btn-mini .rst-content h6 .headerlink:before,.rst-content h6 .btn-mini .headerlink:before,.btn-mini .rst-content dl dt .headerlink:before,.rst-content dl dt .btn-mini .headerlink:before,.btn-mini .rst-content p .headerlink:before,.rst-content p .btn-mini .headerlink:before,.btn-mini .rst-content table>caption .headerlink:before,.rst-content table>caption .btn-mini .headerlink:before,.btn-mini .rst-content .code-block-caption .headerlink:before,.rst-content .code-block-caption .btn-mini .headerlink:before,.btn-mini .rst-content .eqno .headerlink:before,.rst-content .eqno .btn-mini .headerlink:before,.btn-mini .rst-content tt.download span:first-child:before,.rst-content tt.download .btn-mini span:first-child:before,.btn-mini .rst-content code.download span:first-child:before,.rst-content code.download .btn-mini span:first-child:before,.btn-mini .icon:before{font-size:14px;vertical-align:-15%}.wy-alert,.rst-content .note,.rst-content .attention,.rst-content .caution,.rst-content .danger,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .tip,.rst-content .warning,.rst-content .seealso,.rst-content .admonition-todo,.rst-content .admonition{padding:12px;line-height:24px;margin-bottom:24px;background:#e7f2fa}.wy-alert-title,.rst-content .admonition-title{color:#fff;font-weight:bold;display:block;color:#fff;background:#6ab0de;margin:-12px;padding:6px 12px;margin-bottom:12px}.wy-alert.wy-alert-danger,.rst-content .wy-alert-danger.note,.rst-content .wy-alert-danger.attention,.rst-content .wy-alert-danger.caution,.rst-content .danger,.rst-content .error,.rst-content .wy-alert-danger.hint,.rst-content .wy-alert-danger.important,.rst-content .wy-alert-danger.tip,.rst-content .wy-alert-danger.warning,.rst-content .wy-alert-danger.seealso,.rst-content .wy-alert-danger.admonition-todo,.rst-content .wy-alert-danger.admonition{background:#fdf3f2}.wy-alert.wy-alert-danger .wy-alert-title,.rst-content .wy-alert-danger.note .wy-alert-title,.rst-content .wy-alert-danger.attention .wy-alert-title,.rst-content .wy-alert-danger.caution .wy-alert-title,.rst-content .danger .wy-alert-title,.rst-content .error .wy-alert-title,.rst-content .wy-alert-danger.hint .wy-alert-title,.rst-content .wy-alert-danger.important .wy-alert-title,.rst-content .wy-alert-danger.tip .wy-alert-title,.rst-content .wy-alert-danger.warning .wy-alert-title,.rst-content .wy-alert-danger.seealso .wy-alert-title,.rst-content .wy-alert-danger.admonition-todo .wy-alert-title,.rst-content .wy-alert-danger.admonition .wy-alert-title,.wy-alert.wy-alert-danger .rst-content .admonition-title,.rst-content .wy-alert.wy-alert-danger .admonition-title,.rst-content .wy-alert-danger.note .admonition-title,.rst-content .wy-alert-danger.attention .admonition-title,.rst-content .wy-alert-danger.caution .admonition-title,.rst-content .danger .admonition-title,.rst-content .error .admonition-title,.rst-content .wy-alert-danger.hint .admonition-title,.rst-content .wy-alert-danger.important .admonition-title,.rst-content .wy-alert-danger.tip .admonition-title,.rst-content .wy-alert-danger.warning .admonition-title,.rst-content .wy-alert-danger.seealso .admonition-title,.rst-content .wy-alert-danger.admonition-todo .admonition-title,.rst-content .wy-alert-danger.admonition .admonition-title{background:#f29f97}.wy-alert.wy-alert-warning,.rst-content .wy-alert-warning.note,.rst-content .attention,.rst-content .caution,.rst-content .wy-alert-warning.danger,.rst-content .wy-alert-warning.error,.rst-content .wy-alert-warning.hint,.rst-content .wy-alert-warning.important,.rst-content .wy-alert-warning.tip,.rst-content .warning,.rst-content .wy-alert-warning.seealso,.rst-content .admonition-todo,.rst-content .wy-alert-warning.admonition{background:#ffedcc}.wy-alert.wy-alert-warning .wy-alert-title,.rst-content .wy-alert-warning.note .wy-alert-title,.rst-content .attention .wy-alert-title,.rst-content .caution .wy-alert-title,.rst-content .wy-alert-warning.danger .wy-alert-title,.rst-content .wy-alert-warning.error .wy-alert-title,.rst-content .wy-alert-warning.hint .wy-alert-title,.rst-content .wy-alert-warning.important .wy-alert-title,.rst-content .wy-alert-warning.tip .wy-alert-title,.rst-content .warning .wy-alert-title,.rst-content .wy-alert-warning.seealso .wy-alert-title,.rst-content .admonition-todo .wy-alert-title,.rst-content .wy-alert-warning.admonition .wy-alert-title,.wy-alert.wy-alert-warning .rst-content .admonition-title,.rst-content .wy-alert.wy-alert-warning .admonition-title,.rst-content .wy-alert-warning.note .admonition-title,.rst-content .attention .admonition-title,.rst-content .caution .admonition-title,.rst-content .wy-alert-warning.danger .admonition-title,.rst-content .wy-alert-warning.error .admonition-title,.rst-content .wy-alert-warning.hint .admonition-title,.rst-content .wy-alert-warning.important .admonition-title,.rst-content .wy-alert-warning.tip .admonition-title,.rst-content .warning .admonition-title,.rst-content .wy-alert-warning.seealso .admonition-title,.rst-content .admonition-todo .admonition-title,.rst-content .wy-alert-warning.admonition .admonition-title{background:#f0b37e}.wy-alert.wy-alert-info,.rst-content .note,.rst-content .wy-alert-info.attention,.rst-content .wy-alert-info.caution,.rst-content .wy-alert-info.danger,.rst-content .wy-alert-info.error,.rst-content .wy-alert-info.hint,.rst-content .wy-alert-info.important,.rst-content .wy-alert-info.tip,.rst-content .wy-alert-info.warning,.rst-content .seealso,.rst-content .wy-alert-info.admonition-todo,.rst-content .wy-alert-info.admonition{background:#e7f2fa}.wy-alert.wy-alert-info .wy-alert-title,.rst-content .note .wy-alert-title,.rst-content .wy-alert-info.attention .wy-alert-title,.rst-content .wy-alert-info.caution .wy-alert-title,.rst-content .wy-alert-info.danger .wy-alert-title,.rst-content .wy-alert-info.error .wy-alert-title,.rst-content .wy-alert-info.hint .wy-alert-title,.rst-content .wy-alert-info.important .wy-alert-title,.rst-content .wy-alert-info.tip .wy-alert-title,.rst-content .wy-alert-info.warning .wy-alert-title,.rst-content .seealso .wy-alert-title,.rst-content .wy-alert-info.admonition-todo .wy-alert-title,.rst-content .wy-alert-info.admonition .wy-alert-title,.wy-alert.wy-alert-info .rst-content .admonition-title,.rst-content .wy-alert.wy-alert-info .admonition-title,.rst-content .note .admonition-title,.rst-content .wy-alert-info.attention .admonition-title,.rst-content .wy-alert-info.caution .admonition-title,.rst-content .wy-alert-info.danger .admonition-title,.rst-content .wy-alert-info.error .admonition-title,.rst-content .wy-alert-info.hint .admonition-title,.rst-content .wy-alert-info.important .admonition-title,.rst-content .wy-alert-info.tip .admonition-title,.rst-content .wy-alert-info.warning .admonition-title,.rst-content .seealso .admonition-title,.rst-content .wy-alert-info.admonition-todo .admonition-title,.rst-content .wy-alert-info.admonition .admonition-title{background:#6ab0de}.wy-alert.wy-alert-success,.rst-content .wy-alert-success.note,.rst-content .wy-alert-success.attention,.rst-content .wy-alert-success.caution,.rst-content .wy-alert-success.danger,.rst-content .wy-alert-success.error,.rst-content .hint,.rst-content .important,.rst-content .tip,.rst-content .wy-alert-success.warning,.rst-content .wy-alert-success.seealso,.rst-content .wy-alert-success.admonition-todo,.rst-content .wy-alert-success.admonition{background:#dbfaf4}.wy-alert.wy-alert-success .wy-alert-title,.rst-content .wy-alert-success.note .wy-alert-title,.rst-content .wy-alert-success.attention .wy-alert-title,.rst-content .wy-alert-success.caution .wy-alert-title,.rst-content .wy-alert-success.danger .wy-alert-title,.rst-content .wy-alert-success.error .wy-alert-title,.rst-content .hint .wy-alert-title,.rst-content .important .wy-alert-title,.rst-content .tip .wy-alert-title,.rst-content .wy-alert-success.warning .wy-alert-title,.rst-content .wy-alert-success.seealso .wy-alert-title,.rst-content .wy-alert-success.admonition-todo .wy-alert-title,.rst-content .wy-alert-success.admonition .wy-alert-title,.wy-alert.wy-alert-success .rst-content .admonition-title,.rst-content .wy-alert.wy-alert-success .admonition-title,.rst-content .wy-alert-success.note .admonition-title,.rst-content .wy-alert-success.attention .admonition-title,.rst-content .wy-alert-success.caution .admonition-title,.rst-content .wy-alert-success.danger .admonition-title,.rst-content .wy-alert-success.error .admonition-title,.rst-content .hint .admonition-title,.rst-content .important .admonition-title,.rst-content .tip .admonition-title,.rst-content .wy-alert-success.warning .admonition-title,.rst-content .wy-alert-success.seealso .admonition-title,.rst-content .wy-alert-success.admonition-todo .admonition-title,.rst-content .wy-alert-success.admonition .admonition-title{background:#1abc9c}.wy-alert.wy-alert-neutral,.rst-content .wy-alert-neutral.note,.rst-content .wy-alert-neutral.attention,.rst-content .wy-alert-neutral.caution,.rst-content .wy-alert-neutral.danger,.rst-content .wy-alert-neutral.error,.rst-content .wy-alert-neutral.hint,.rst-content .wy-alert-neutral.important,.rst-content .wy-alert-neutral.tip,.rst-content .wy-alert-neutral.warning,.rst-content .wy-alert-neutral.seealso,.rst-content .wy-alert-neutral.admonition-todo,.rst-content .wy-alert-neutral.admonition{background:#f3f6f6}.wy-alert.wy-alert-neutral .wy-alert-title,.rst-content .wy-alert-neutral.note .wy-alert-title,.rst-content .wy-alert-neutral.attention .wy-alert-title,.rst-content .wy-alert-neutral.caution .wy-alert-title,.rst-content .wy-alert-neutral.danger .wy-alert-title,.rst-content .wy-alert-neutral.error .wy-alert-title,.rst-content .wy-alert-neutral.hint .wy-alert-title,.rst-content .wy-alert-neutral.important .wy-alert-title,.rst-content .wy-alert-neutral.tip .wy-alert-title,.rst-content .wy-alert-neutral.warning .wy-alert-title,.rst-content .wy-alert-neutral.seealso .wy-alert-title,.rst-content .wy-alert-neutral.admonition-todo .wy-alert-title,.rst-content .wy-alert-neutral.admonition .wy-alert-title,.wy-alert.wy-alert-neutral .rst-content .admonition-title,.rst-content .wy-alert.wy-alert-neutral .admonition-title,.rst-content .wy-alert-neutral.note .admonition-title,.rst-content .wy-alert-neutral.attention .admonition-title,.rst-content .wy-alert-neutral.caution .admonition-title,.rst-content .wy-alert-neutral.danger .admonition-title,.rst-content .wy-alert-neutral.error .admonition-title,.rst-content .wy-alert-neutral.hint .admonition-title,.rst-content .wy-alert-neutral.important .admonition-title,.rst-content .wy-alert-neutral.tip .admonition-title,.rst-content .wy-alert-neutral.warning .admonition-title,.rst-content .wy-alert-neutral.seealso .admonition-title,.rst-content .wy-alert-neutral.admonition-todo .admonition-title,.rst-content .wy-alert-neutral.admonition .admonition-title{color:#404040;background:#e1e4e5}.wy-alert.wy-alert-neutral a,.rst-content .wy-alert-neutral.note a,.rst-content .wy-alert-neutral.attention a,.rst-content .wy-alert-neutral.caution a,.rst-content .wy-alert-neutral.danger a,.rst-content .wy-alert-neutral.error a,.rst-content .wy-alert-neutral.hint a,.rst-content .wy-alert-neutral.important a,.rst-content .wy-alert-neutral.tip a,.rst-content .wy-alert-neutral.warning a,.rst-content .wy-alert-neutral.seealso a,.rst-content .wy-alert-neutral.admonition-todo a,.rst-content .wy-alert-neutral.admonition a{color:#2980B9}.wy-alert p:last-child,.rst-content .note p:last-child,.rst-content .attention p:last-child,.rst-content .caution p:last-child,.rst-content .danger p:last-child,.rst-content .error p:last-child,.rst-content .hint p:last-child,.rst-content .important p:last-child,.rst-content .tip p:last-child,.rst-content .warning p:last-child,.rst-content .seealso p:last-child,.rst-content .admonition-todo p:last-child,.rst-content .admonition p:last-child{margin-bottom:0}.wy-tray-container{position:fixed;bottom:0px;left:0;z-index:600}.wy-tray-container li{display:block;width:300px;background:transparent;color:#fff;text-align:center;box-shadow:0 5px 5px 0 rgba(0,0,0,0.1);padding:0 24px;min-width:20%;opacity:0;height:0;line-height:56px;overflow:hidden;-webkit-transition:all .3s ease-in;-moz-transition:all .3s ease-in;transition:all .3s ease-in}.wy-tray-container li.wy-tray-item-success{background:#27AE60}.wy-tray-container li.wy-tray-item-info{background:#2980B9}.wy-tray-container li.wy-tray-item-warning{background:#E67E22}.wy-tray-container li.wy-tray-item-danger{background:#E74C3C}.wy-tray-container li.on{opacity:1;height:56px}@media screen and (max-width: 768px){.wy-tray-container{bottom:auto;top:0;width:100%}.wy-tray-container li{width:100%}}button{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle;cursor:pointer;line-height:normal;-webkit-appearance:button;*overflow:visible}button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}button[disabled]{cursor:default}.btn{display:inline-block;border-radius:2px;line-height:normal;white-space:nowrap;text-align:center;cursor:pointer;font-size:100%;padding:6px 12px 8px 12px;color:#fff;border:1px solid rgba(0,0,0,0.1);background-color:#27AE60;text-decoration:none;font-weight:normal;font-family:"Lato","proxima-nova","Helvetica Neue",Arial,sans-serif;box-shadow:0px 1px 2px -1px rgba(255,255,255,0.5) inset,0px -2px 0px 0px rgba(0,0,0,0.1) inset;outline-none:false;vertical-align:middle;*display:inline;zoom:1;-webkit-user-drag:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;-webkit-transition:all .1s linear;-moz-transition:all .1s linear;transition:all .1s linear}.btn-hover{background:#2e8ece;color:#fff}.btn:hover{background:#2cc36b;color:#fff}.btn:focus{background:#2cc36b;outline:0}.btn:active{box-shadow:0px -1px 0px 0px rgba(0,0,0,0.05) inset,0px 2px 0px 0px rgba(0,0,0,0.1) inset;padding:8px 12px 6px 12px}.btn:visited{color:#fff}.btn:disabled{background-image:none;filter:progid:DXImageTransform.Microsoft.gradient(enabled = false);filter:alpha(opacity=40);opacity:.4;cursor:not-allowed;box-shadow:none}.btn-disabled{background-image:none;filter:progid:DXImageTransform.Microsoft.gradient(enabled = false);filter:alpha(opacity=40);opacity:.4;cursor:not-allowed;box-shadow:none}.btn-disabled:hover,.btn-disabled:focus,.btn-disabled:active{background-image:none;filter:progid:DXImageTransform.Microsoft.gradient(enabled = false);filter:alpha(opacity=40);opacity:.4;cursor:not-allowed;box-shadow:none}.btn::-moz-focus-inner{padding:0;border:0}.btn-small{font-size:80%}.btn-info{background-color:#2980B9 !important}.btn-info:hover{background-color:#2e8ece !important}.btn-neutral{background-color:#f3f6f6 !important;color:#404040 !important}.btn-neutral:hover{background-color:#e5ebeb !important;color:#404040}.btn-neutral:visited{color:#404040 !important}.btn-success{background-color:#27AE60 !important}.btn-success:hover{background-color:#295 !important}.btn-danger{background-color:#E74C3C !important}.btn-danger:hover{background-color:#ea6153 !important}.btn-warning{background-color:#E67E22 !important}.btn-warning:hover{background-color:#e98b39 !important}.btn-invert{background-color:#222}.btn-invert:hover{background-color:#2f2f2f !important}.btn-link{background-color:transparent !important;color:#2980B9;box-shadow:none;border-color:transparent !important}.btn-link:hover{background-color:transparent !important;color:#409ad5 !important;box-shadow:none}.btn-link:active{background-color:transparent !important;color:#409ad5 !important;box-shadow:none}.btn-link:visited{color:#9B59B6}.wy-btn-group .btn,.wy-control .btn{vertical-align:middle}.wy-btn-group{margin-bottom:24px;*zoom:1}.wy-btn-group:before,.wy-btn-group:after{display:table;content:""}.wy-btn-group:after{clear:both}.wy-dropdown{position:relative;display:inline-block}.wy-dropdown-active .wy-dropdown-menu{display:block}.wy-dropdown-menu{position:absolute;left:0;display:none;float:left;top:100%;min-width:100%;background:#fcfcfc;z-index:100;border:solid 1px #cfd7dd;box-shadow:0 2px 2px 0 rgba(0,0,0,0.1);padding:12px}.wy-dropdown-menu>dd>a{display:block;clear:both;color:#404040;white-space:nowrap;font-size:90%;padding:0 12px;cursor:pointer}.wy-dropdown-menu>dd>a:hover{background:#2980B9;color:#fff}.wy-dropdown-menu>dd.divider{border-top:solid 1px #cfd7dd;margin:6px 0}.wy-dropdown-menu>dd.search{padding-bottom:12px}.wy-dropdown-menu>dd.search input[type="search"]{width:100%}.wy-dropdown-menu>dd.call-to-action{background:#e3e3e3;text-transform:uppercase;font-weight:500;font-size:80%}.wy-dropdown-menu>dd.call-to-action:hover{background:#e3e3e3}.wy-dropdown-menu>dd.call-to-action .btn{color:#fff}.wy-dropdown.wy-dropdown-up .wy-dropdown-menu{bottom:100%;top:auto;left:auto;right:0}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu{background:#fcfcfc;margin-top:2px}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu a{padding:6px 12px}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu a:hover{background:#2980B9;color:#fff}.wy-dropdown.wy-dropdown-left .wy-dropdown-menu{right:0;left:auto;text-align:right}.wy-dropdown-arrow:before{content:" ";border-bottom:5px solid #f5f5f5;border-left:5px solid transparent;border-right:5px solid transparent;position:absolute;display:block;top:-4px;left:50%;margin-left:-3px}.wy-dropdown-arrow.wy-dropdown-arrow-left:before{left:11px}.wy-form-stacked select{display:block}.wy-form-aligned input,.wy-form-aligned textarea,.wy-form-aligned select,.wy-form-aligned .wy-help-inline,.wy-form-aligned label{display:inline-block;*display:inline;*zoom:1;vertical-align:middle}.wy-form-aligned .wy-control-group>label{display:inline-block;vertical-align:middle;width:10em;margin:6px 12px 0 0;float:left}.wy-form-aligned .wy-control{float:left}.wy-form-aligned .wy-control label{display:block}.wy-form-aligned .wy-control select{margin-top:6px}fieldset{border:0;margin:0;padding:0}legend{display:block;width:100%;border:0;padding:0;white-space:normal;margin-bottom:24px;font-size:150%;*margin-left:-7px}label{display:block;margin:0 0 .3125em 0;color:#333;font-size:90%}input,select,textarea{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle}.wy-control-group{margin-bottom:24px;*zoom:1;max-width:1200px;margin-left:auto;margin-right:auto;*zoom:1}.wy-control-group:before,.wy-control-group:after{display:table;content:""}.wy-control-group:after{clear:both}.wy-control-group:before,.wy-control-group:after{display:table;content:""}.wy-control-group:after{clear:both}.wy-control-group.wy-control-group-required>label:after{content:" *";color:#E74C3C}.wy-control-group .wy-form-full,.wy-control-group .wy-form-halves,.wy-control-group .wy-form-thirds{padding-bottom:12px}.wy-control-group .wy-form-full select,.wy-control-group .wy-form-halves select,.wy-control-group .wy-form-thirds select{width:100%}.wy-control-group .wy-form-full input[type="text"],.wy-control-group .wy-form-full input[type="password"],.wy-control-group .wy-form-full input[type="email"],.wy-control-group .wy-form-full input[type="url"],.wy-control-group .wy-form-full input[type="date"],.wy-control-group .wy-form-full input[type="month"],.wy-control-group .wy-form-full input[type="time"],.wy-control-group .wy-form-full input[type="datetime"],.wy-control-group .wy-form-full input[type="datetime-local"],.wy-control-group .wy-form-full input[type="week"],.wy-control-group .wy-form-full input[type="number"],.wy-control-group .wy-form-full input[type="search"],.wy-control-group .wy-form-full input[type="tel"],.wy-control-group .wy-form-full input[type="color"],.wy-control-group .wy-form-halves input[type="text"],.wy-control-group .wy-form-halves input[type="password"],.wy-control-group .wy-form-halves input[type="email"],.wy-control-group .wy-form-halves input[type="url"],.wy-control-group .wy-form-halves input[type="date"],.wy-control-group .wy-form-halves input[type="month"],.wy-control-group .wy-form-halves input[type="time"],.wy-control-group .wy-form-halves input[type="datetime"],.wy-control-group .wy-form-halves input[type="datetime-local"],.wy-control-group .wy-form-halves input[type="week"],.wy-control-group .wy-form-halves input[type="number"],.wy-control-group .wy-form-halves input[type="search"],.wy-control-group .wy-form-halves input[type="tel"],.wy-control-group .wy-form-halves input[type="color"],.wy-control-group .wy-form-thirds input[type="text"],.wy-control-group .wy-form-thirds input[type="password"],.wy-control-group .wy-form-thirds input[type="email"],.wy-control-group .wy-form-thirds input[type="url"],.wy-control-group .wy-form-thirds input[type="date"],.wy-control-group .wy-form-thirds input[type="month"],.wy-control-group .wy-form-thirds input[type="time"],.wy-control-group .wy-form-thirds input[type="datetime"],.wy-control-group .wy-form-thirds input[type="datetime-local"],.wy-control-group .wy-form-thirds input[type="week"],.wy-control-group .wy-form-thirds input[type="number"],.wy-control-group .wy-form-thirds input[type="search"],.wy-control-group .wy-form-thirds input[type="tel"],.wy-control-group .wy-form-thirds input[type="color"]{width:100%}.wy-control-group .wy-form-full{float:left;display:block;margin-right:2.3576520234%;width:100%;margin-right:0}.wy-control-group .wy-form-full:last-child{margin-right:0}.wy-control-group .wy-form-halves{float:left;display:block;margin-right:2.3576520234%;width:48.8211739883%}.wy-control-group .wy-form-halves:last-child{margin-right:0}.wy-control-group .wy-form-halves:nth-of-type(2n){margin-right:0}.wy-control-group .wy-form-halves:nth-of-type(2n+1){clear:left}.wy-control-group .wy-form-thirds{float:left;display:block;margin-right:2.3576520234%;width:31.7615653177%}.wy-control-group .wy-form-thirds:last-child{margin-right:0}.wy-control-group .wy-form-thirds:nth-of-type(3n){margin-right:0}.wy-control-group .wy-form-thirds:nth-of-type(3n+1){clear:left}.wy-control-group.wy-control-group-no-input .wy-control{margin:6px 0 0 0;font-size:90%}.wy-control-no-input{display:inline-block;margin:6px 0 0 0;font-size:90%}.wy-control-group.fluid-input input[type="text"],.wy-control-group.fluid-input input[type="password"],.wy-control-group.fluid-input input[type="email"],.wy-control-group.fluid-input input[type="url"],.wy-control-group.fluid-input input[type="date"],.wy-control-group.fluid-input input[type="month"],.wy-control-group.fluid-input input[type="time"],.wy-control-group.fluid-input input[type="datetime"],.wy-control-group.fluid-input input[type="datetime-local"],.wy-control-group.fluid-input input[type="week"],.wy-control-group.fluid-input input[type="number"],.wy-control-group.fluid-input input[type="search"],.wy-control-group.fluid-input input[type="tel"],.wy-control-group.fluid-input input[type="color"]{width:100%}.wy-form-message-inline{display:inline-block;padding-left:.3em;color:#666;vertical-align:middle;font-size:90%}.wy-form-message{display:block;color:#999;font-size:70%;margin-top:.3125em;font-style:italic}.wy-form-message p{font-size:inherit;font-style:italic;margin-bottom:6px}.wy-form-message p:last-child{margin-bottom:0}input{line-height:normal}input[type="button"],input[type="reset"],input[type="submit"]{-webkit-appearance:button;cursor:pointer;font-family:"Lato","proxima-nova","Helvetica Neue",Arial,sans-serif;*overflow:visible}input[type="text"],input[type="password"],input[type="email"],input[type="url"],input[type="date"],input[type="month"],input[type="time"],input[type="datetime"],input[type="datetime-local"],input[type="week"],input[type="number"],input[type="search"],input[type="tel"],input[type="color"]{-webkit-appearance:none;padding:6px;display:inline-block;border:1px solid #ccc;font-size:80%;font-family:"Lato","proxima-nova","Helvetica Neue",Arial,sans-serif;box-shadow:inset 0 1px 3px #ddd;border-radius:0;-webkit-transition:border .3s linear;-moz-transition:border .3s linear;transition:border .3s linear}input[type="datetime-local"]{padding:.34375em .625em}input[disabled]{cursor:default}input[type="checkbox"],input[type="radio"]{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box;padding:0;margin-right:.3125em;*height:13px;*width:13px}input[type="search"]{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}input[type="search"]::-webkit-search-cancel-button,input[type="search"]::-webkit-search-decoration{-webkit-appearance:none}input[type="text"]:focus,input[type="password"]:focus,input[type="email"]:focus,input[type="url"]:focus,input[type="date"]:focus,input[type="month"]:focus,input[type="time"]:focus,input[type="datetime"]:focus,input[type="datetime-local"]:focus,input[type="week"]:focus,input[type="number"]:focus,input[type="search"]:focus,input[type="tel"]:focus,input[type="color"]:focus{outline:0;outline:thin dotted \9 ;border-color:#333}input.no-focus:focus{border-color:#ccc !important}input[type="file"]:focus,input[type="radio"]:focus,input[type="checkbox"]:focus{outline:thin dotted #333;outline:1px auto #129FEA}input[type="text"][disabled],input[type="password"][disabled],input[type="email"][disabled],input[type="url"][disabled],input[type="date"][disabled],input[type="month"][disabled],input[type="time"][disabled],input[type="datetime"][disabled],input[type="datetime-local"][disabled],input[type="week"][disabled],input[type="number"][disabled],input[type="search"][disabled],input[type="tel"][disabled],input[type="color"][disabled]{cursor:not-allowed;background-color:#fafafa}input:focus:invalid,textarea:focus:invalid,select:focus:invalid{color:#E74C3C;border:1px solid #E74C3C}input:focus:invalid:focus,textarea:focus:invalid:focus,select:focus:invalid:focus{border-color:#E74C3C}input[type="file"]:focus:invalid:focus,input[type="radio"]:focus:invalid:focus,input[type="checkbox"]:focus:invalid:focus{outline-color:#E74C3C}input.wy-input-large{padding:12px;font-size:100%}textarea{overflow:auto;vertical-align:top;width:100%;font-family:"Lato","proxima-nova","Helvetica Neue",Arial,sans-serif}select,textarea{padding:.5em .625em;display:inline-block;border:1px solid #ccc;font-size:80%;box-shadow:inset 0 1px 3px #ddd;-webkit-transition:border .3s linear;-moz-transition:border .3s linear;transition:border .3s linear}select{border:1px solid #ccc;background-color:#fff}select[multiple]{height:auto}select:focus,textarea:focus{outline:0}select[disabled],textarea[disabled],input[readonly],select[readonly],textarea[readonly]{cursor:not-allowed;background-color:#fafafa}input[type="radio"][disabled],input[type="checkbox"][disabled]{cursor:not-allowed}.wy-checkbox,.wy-radio{margin:6px 0;color:#404040;display:block}.wy-checkbox input,.wy-radio input{vertical-align:baseline}.wy-form-message-inline{display:inline-block;*display:inline;*zoom:1;vertical-align:middle}.wy-input-prefix,.wy-input-suffix{white-space:nowrap;padding:6px}.wy-input-prefix .wy-input-context,.wy-input-suffix .wy-input-context{line-height:27px;padding:0 8px;display:inline-block;font-size:80%;background-color:#f3f6f6;border:solid 1px #ccc;color:#999}.wy-input-suffix .wy-input-context{border-left:0}.wy-input-prefix .wy-input-context{border-right:0}.wy-switch{position:relative;display:block;height:24px;margin-top:12px;cursor:pointer}.wy-switch:before{position:absolute;content:"";display:block;left:0;top:0;width:36px;height:12px;border-radius:4px;background:#ccc;-webkit-transition:all .2s ease-in-out;-moz-transition:all .2s ease-in-out;transition:all .2s ease-in-out}.wy-switch:after{position:absolute;content:"";display:block;width:18px;height:18px;border-radius:4px;background:#999;left:-3px;top:-3px;-webkit-transition:all .2s ease-in-out;-moz-transition:all .2s ease-in-out;transition:all .2s ease-in-out}.wy-switch span{position:absolute;left:48px;display:block;font-size:12px;color:#ccc;line-height:1}.wy-switch.active:before{background:#1e8449}.wy-switch.active:after{left:24px;background:#27AE60}.wy-switch.disabled{cursor:not-allowed;opacity:.8}.wy-control-group.wy-control-group-error .wy-form-message,.wy-control-group.wy-control-group-error>label{color:#E74C3C}.wy-control-group.wy-control-group-error input[type="text"],.wy-control-group.wy-control-group-error input[type="password"],.wy-control-group.wy-control-group-error input[type="email"],.wy-control-group.wy-control-group-error input[type="url"],.wy-control-group.wy-control-group-error input[type="date"],.wy-control-group.wy-control-group-error input[type="month"],.wy-control-group.wy-control-group-error input[type="time"],.wy-control-group.wy-control-group-error input[type="datetime"],.wy-control-group.wy-control-group-error input[type="datetime-local"],.wy-control-group.wy-control-group-error input[type="week"],.wy-control-group.wy-control-group-error input[type="number"],.wy-control-group.wy-control-group-error input[type="search"],.wy-control-group.wy-control-group-error input[type="tel"],.wy-control-group.wy-control-group-error input[type="color"]{border:solid 1px #E74C3C}.wy-control-group.wy-control-group-error textarea{border:solid 1px #E74C3C}.wy-inline-validate{white-space:nowrap}.wy-inline-validate .wy-input-context{padding:.5em .625em;display:inline-block;font-size:80%}.wy-inline-validate.wy-inline-validate-success .wy-input-context{color:#27AE60}.wy-inline-validate.wy-inline-validate-danger .wy-input-context{color:#E74C3C}.wy-inline-validate.wy-inline-validate-warning .wy-input-context{color:#E67E22}.wy-inline-validate.wy-inline-validate-info .wy-input-context{color:#2980B9}.rotate-90{-webkit-transform:rotate(90deg);-moz-transform:rotate(90deg);-ms-transform:rotate(90deg);-o-transform:rotate(90deg);transform:rotate(90deg)}.rotate-180{-webkit-transform:rotate(180deg);-moz-transform:rotate(180deg);-ms-transform:rotate(180deg);-o-transform:rotate(180deg);transform:rotate(180deg)}.rotate-270{-webkit-transform:rotate(270deg);-moz-transform:rotate(270deg);-ms-transform:rotate(270deg);-o-transform:rotate(270deg);transform:rotate(270deg)}.mirror{-webkit-transform:scaleX(-1);-moz-transform:scaleX(-1);-ms-transform:scaleX(-1);-o-transform:scaleX(-1);transform:scaleX(-1)}.mirror.rotate-90{-webkit-transform:scaleX(-1) rotate(90deg);-moz-transform:scaleX(-1) rotate(90deg);-ms-transform:scaleX(-1) rotate(90deg);-o-transform:scaleX(-1) rotate(90deg);transform:scaleX(-1) rotate(90deg)}.mirror.rotate-180{-webkit-transform:scaleX(-1) rotate(180deg);-moz-transform:scaleX(-1) rotate(180deg);-ms-transform:scaleX(-1) rotate(180deg);-o-transform:scaleX(-1) rotate(180deg);transform:scaleX(-1) rotate(180deg)}.mirror.rotate-270{-webkit-transform:scaleX(-1) rotate(270deg);-moz-transform:scaleX(-1) rotate(270deg);-ms-transform:scaleX(-1) rotate(270deg);-o-transform:scaleX(-1) rotate(270deg);transform:scaleX(-1) rotate(270deg)}@media only screen and (max-width: 480px){.wy-form button[type="submit"]{margin:.7em 0 0}.wy-form input[type="text"],.wy-form input[type="password"],.wy-form input[type="email"],.wy-form input[type="url"],.wy-form input[type="date"],.wy-form input[type="month"],.wy-form input[type="time"],.wy-form input[type="datetime"],.wy-form input[type="datetime-local"],.wy-form input[type="week"],.wy-form input[type="number"],.wy-form input[type="search"],.wy-form input[type="tel"],.wy-form input[type="color"]{margin-bottom:.3em;display:block}.wy-form label{margin-bottom:.3em;display:block}.wy-form input[type="password"],.wy-form input[type="email"],.wy-form input[type="url"],.wy-form input[type="date"],.wy-form input[type="month"],.wy-form input[type="time"],.wy-form input[type="datetime"],.wy-form input[type="datetime-local"],.wy-form input[type="week"],.wy-form input[type="number"],.wy-form input[type="search"],.wy-form input[type="tel"],.wy-form input[type="color"]{margin-bottom:0}.wy-form-aligned .wy-control-group label{margin-bottom:.3em;text-align:left;display:block;width:100%}.wy-form-aligned .wy-control{margin:1.5em 0 0 0}.wy-form .wy-help-inline,.wy-form-message-inline,.wy-form-message{display:block;font-size:80%;padding:6px 0}}@media screen and (max-width: 768px){.tablet-hide{display:none}}@media screen and (max-width: 480px){.mobile-hide{display:none}}.float-left{float:left}.float-right{float:right}.full-width{width:100%}.wy-table,.rst-content table.docutils,.rst-content table.field-list{border-collapse:collapse;border-spacing:0;empty-cells:show;margin-bottom:24px}.wy-table caption,.rst-content table.docutils caption,.rst-content table.field-list caption{color:#000;font:italic 85%/1 arial,sans-serif;padding:1em 0;text-align:center}.wy-table td,.rst-content table.docutils td,.rst-content table.field-list td,.wy-table th,.rst-content table.docutils th,.rst-content table.field-list th{font-size:90%;margin:0;overflow:visible;padding:8px 16px}.wy-table td:first-child,.rst-content table.docutils td:first-child,.rst-content table.field-list td:first-child,.wy-table th:first-child,.rst-content table.docutils th:first-child,.rst-content table.field-list th:first-child{border-left-width:0}.wy-table thead,.rst-content table.docutils thead,.rst-content table.field-list thead{color:#000;text-align:left;vertical-align:bottom;white-space:nowrap}.wy-table thead th,.rst-content table.docutils thead th,.rst-content table.field-list thead th{font-weight:bold;border-bottom:solid 2px #e1e4e5}.wy-table td,.rst-content table.docutils td,.rst-content table.field-list td{background-color:transparent;vertical-align:middle}.wy-table td p,.rst-content table.docutils td p,.rst-content table.field-list td p{line-height:18px}.wy-table td p:last-child,.rst-content table.docutils td p:last-child,.rst-content table.field-list td p:last-child{margin-bottom:0}.wy-table .wy-table-cell-min,.rst-content table.docutils .wy-table-cell-min,.rst-content table.field-list .wy-table-cell-min{width:1%;padding-right:0}.wy-table .wy-table-cell-min input[type=checkbox],.rst-content table.docutils .wy-table-cell-min input[type=checkbox],.rst-content table.field-list .wy-table-cell-min input[type=checkbox],.wy-table .wy-table-cell-min input[type=checkbox],.rst-content table.docutils .wy-table-cell-min input[type=checkbox],.rst-content table.field-list .wy-table-cell-min input[type=checkbox]{margin:0}.wy-table-secondary{color:gray;font-size:90%}.wy-table-tertiary{color:gray;font-size:80%}.wy-table-odd td,.wy-table-striped tr:nth-child(2n-1) td,.rst-content table.docutils:not(.field-list) tr:nth-child(2n-1) td{background-color:#f3f6f6}.wy-table-backed{background-color:#f3f6f6}.wy-table-bordered-all,.rst-content table.docutils{border:1px solid #e1e4e5}.wy-table-bordered-all td,.rst-content table.docutils td{border-bottom:1px solid #e1e4e5;border-left:1px solid #e1e4e5}.wy-table-bordered-all tbody>tr:last-child td,.rst-content table.docutils tbody>tr:last-child td{border-bottom-width:0}.wy-table-bordered{border:1px solid #e1e4e5}.wy-table-bordered-rows td{border-bottom:1px solid #e1e4e5}.wy-table-bordered-rows tbody>tr:last-child td{border-bottom-width:0}.wy-table-horizontal tbody>tr:last-child td{border-bottom-width:0}.wy-table-horizontal td,.wy-table-horizontal th{border-width:0 0 1px 0;border-bottom:1px solid #e1e4e5}.wy-table-horizontal tbody>tr:last-child td{border-bottom-width:0}.wy-table-responsive{margin-bottom:24px;max-width:100%;overflow:auto}.wy-table-responsive table{margin-bottom:0 !important}.wy-table-responsive table td,.wy-table-responsive table th{white-space:nowrap}a{color:#2980B9;text-decoration:none;cursor:pointer}a:hover{color:#3091d1}a:visited{color:#9B59B6}html{height:100%;overflow-x:hidden}body{font-family:"Lato","proxima-nova","Helvetica Neue",Arial,sans-serif;font-weight:normal;color:#404040;min-height:100%;overflow-x:hidden;background:#edf0f2}.wy-text-left{text-align:left}.wy-text-center{text-align:center}.wy-text-right{text-align:right}.wy-text-large{font-size:120%}.wy-text-normal{font-size:100%}.wy-text-small,small{font-size:80%}.wy-text-strike{text-decoration:line-through}.wy-text-warning{color:#E67E22 !important}a.wy-text-warning:hover{color:#eb9950 !important}.wy-text-info{color:#2980B9 !important}a.wy-text-info:hover{color:#409ad5 !important}.wy-text-success{color:#27AE60 !important}a.wy-text-success:hover{color:#36d278 !important}.wy-text-danger{color:#E74C3C !important}a.wy-text-danger:hover{color:#ed7669 !important}.wy-text-neutral{color:#404040 !important}a.wy-text-neutral:hover{color:#595959 !important}h1,h2,.rst-content .toctree-wrapper>p.caption,h3,h4,h5,h6,legend{margin-top:0;font-weight:700;font-family:"Roboto Slab","ff-tisa-web-pro","Georgia",Arial,sans-serif}p{line-height:24px;margin:0;font-size:16px;margin-bottom:24px}h1{font-size:175%}h2,.rst-content .toctree-wrapper>p.caption{font-size:150%}h3{font-size:125%}h4{font-size:115%}h5{font-size:110%}h6{font-size:100%}hr{display:block;height:1px;border:0;border-top:1px solid #e1e4e5;margin:24px 0;padding:0}code,.rst-content tt,.rst-content code{white-space:nowrap;max-width:100%;background:#fff;border:solid 1px #e1e4e5;font-size:75%;padding:0 5px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;color:#E74C3C;overflow-x:auto}code.code-large,.rst-content tt.code-large{font-size:90%}.wy-plain-list-disc,.rst-content .section ul,.rst-content section ul,.rst-content .toctree-wrapper ul,article ul{list-style:disc;line-height:24px;margin-bottom:24px}.wy-plain-list-disc li,.rst-content .section ul li,.rst-content section ul li,.rst-content .toctree-wrapper ul li,article ul li{list-style:disc;margin-left:24px}.wy-plain-list-disc li p:last-child,.rst-content .section ul li p:last-child,.rst-content section ul li p:last-child,.rst-content .toctree-wrapper ul li p:last-child,article ul li p:last-child{margin-bottom:0}.wy-plain-list-disc li ul,.rst-content .section ul li ul,.rst-content section ul li ul,.rst-content .toctree-wrapper ul li ul,article ul li ul{margin-bottom:0}.wy-plain-list-disc li li,.rst-content .section ul li li,.rst-content section ul li li,.rst-content .toctree-wrapper ul li li,article ul li li{list-style:circle}.wy-plain-list-disc li li li,.rst-content .section ul li li li,.rst-content section ul li li li,.rst-content .toctree-wrapper ul li li li,article ul li li li{list-style:square}.wy-plain-list-disc li ol li,.rst-content .section ul li ol li,.rst-content section ul li ol li,.rst-content .toctree-wrapper ul li ol li,article ul li ol li{list-style:decimal}.wy-plain-list-decimal,.rst-content .section ol,.rst-content .section ol.arabic,.rst-content section ol,.rst-content section ol.arabic,.rst-content .toctree-wrapper ol,.rst-content .toctree-wrapper ol.arabic,article ol{list-style:decimal;line-height:24px;margin-bottom:24px}.wy-plain-list-decimal li,.rst-content .section ol li,.rst-content .section ol.arabic li,.rst-content section ol li,.rst-content section ol.arabic li,.rst-content .toctree-wrapper ol li,.rst-content .toctree-wrapper ol.arabic li,article ol li{list-style:decimal;margin-left:24px}.wy-plain-list-decimal li p:last-child,.rst-content .section ol li p:last-child,.rst-content section ol li p:last-child,.rst-content .toctree-wrapper ol li p:last-child,article ol li p:last-child{margin-bottom:0}.wy-plain-list-decimal li ul,.rst-content .section ol li ul,.rst-content .section ol.arabic li ul,.rst-content section ol li ul,.rst-content section ol.arabic li ul,.rst-content .toctree-wrapper ol li ul,.rst-content .toctree-wrapper ol.arabic li ul,article ol li ul{margin-bottom:0}.wy-plain-list-decimal li ul li,.rst-content .section ol li ul li,.rst-content .section ol.arabic li ul li,.rst-content section ol li ul li,.rst-content section ol.arabic li ul li,.rst-content .toctree-wrapper ol li ul li,.rst-content .toctree-wrapper ol.arabic li ul li,article ol li ul li{list-style:disc}.wy-breadcrumbs{*zoom:1}.wy-breadcrumbs:before,.wy-breadcrumbs:after{display:table;content:""}.wy-breadcrumbs:after{clear:both}.wy-breadcrumbs li{display:inline-block}.wy-breadcrumbs li.wy-breadcrumbs-aside{float:right}.wy-breadcrumbs li a{display:inline-block;padding:5px}.wy-breadcrumbs li a:first-child{padding-left:0}.wy-breadcrumbs li code,.wy-breadcrumbs li .rst-content tt,.rst-content .wy-breadcrumbs li tt{padding:5px;border:none;background:none}.wy-breadcrumbs li code.literal,.wy-breadcrumbs li .rst-content tt.literal,.rst-content .wy-breadcrumbs li tt.literal{color:#404040}.wy-breadcrumbs-extra{margin-bottom:0;color:#b3b3b3;font-size:80%;display:inline-block}@media screen and (max-width: 480px){.wy-breadcrumbs-extra{display:none}.wy-breadcrumbs li.wy-breadcrumbs-aside{display:none}}@media print{.wy-breadcrumbs li.wy-breadcrumbs-aside{display:none}}html{font-size:16px}.wy-affix{position:fixed;top:1.618em}.wy-menu a:hover{text-decoration:none}.wy-menu-horiz{*zoom:1}.wy-menu-horiz:before,.wy-menu-horiz:after{display:table;content:""}.wy-menu-horiz:after{clear:both}.wy-menu-horiz ul,.wy-menu-horiz li{display:inline-block}.wy-menu-horiz li:hover{background:rgba(255,255,255,0.1)}.wy-menu-horiz li.divide-left{border-left:solid 1px #404040}.wy-menu-horiz li.divide-right{border-right:solid 1px #404040}.wy-menu-horiz a{height:32px;display:inline-block;line-height:32px;padding:0 16px}.wy-menu-vertical{width:300px}.wy-menu-vertical header,.wy-menu-vertical p.caption{color:#55a5d9;height:32px;line-height:32px;padding:0 1.618em;margin:12px 0 0 0;display:block;font-weight:bold;text-transform:uppercase;font-size:85%;white-space:nowrap}.wy-menu-vertical ul{margin-bottom:0}.wy-menu-vertical li.divide-top{border-top:solid 1px #404040}.wy-menu-vertical li.divide-bottom{border-bottom:solid 1px #404040}.wy-menu-vertical li.current{background:#e3e3e3}.wy-menu-vertical li.current a{color:gray;border-right:solid 1px #c9c9c9;padding:.4045em 2.427em}.wy-menu-vertical li.current a:hover{background:#d6d6d6}.wy-menu-vertical li code,.wy-menu-vertical li .rst-content tt,.rst-content .wy-menu-vertical li tt{border:none;background:inherit;color:inherit;padding-left:0;padding-right:0}.wy-menu-vertical li button.toctree-expand{display:block;float:left;margin-left:-1.2em;line-height:18px;color:#4d4d4d;border:none;background:none;padding:0}.wy-menu-vertical li.on a,.wy-menu-vertical li.current>a{color:#404040;padding:.4045em 1.618em;font-weight:bold;position:relative;background:#fcfcfc;border:none;padding-left:1.618em -4px}.wy-menu-vertical li.on a:hover,.wy-menu-vertical li.current>a:hover{background:#fcfcfc}.wy-menu-vertical li.on a:hover button.toctree-expand,.wy-menu-vertical li.current>a:hover button.toctree-expand{color:gray}.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li.current>a button.toctree-expand{display:block;line-height:18px;color:#333}.wy-menu-vertical li.toctree-l1.current>a{border-bottom:solid 1px #c9c9c9;border-top:solid 1px #c9c9c9}.wy-menu-vertical .toctree-l1.current .toctree-l2>ul,.wy-menu-vertical .toctree-l2.current .toctree-l3>ul,.wy-menu-vertical .toctree-l3.current .toctree-l4>ul,.wy-menu-vertical .toctree-l4.current .toctree-l5>ul,.wy-menu-vertical .toctree-l5.current .toctree-l6>ul,.wy-menu-vertical .toctree-l6.current .toctree-l7>ul,.wy-menu-vertical .toctree-l7.current .toctree-l8>ul,.wy-menu-vertical .toctree-l8.current .toctree-l9>ul,.wy-menu-vertical .toctree-l9.current .toctree-l10>ul,.wy-menu-vertical .toctree-l10.current .toctree-l11>ul{display:none}.wy-menu-vertical .toctree-l1.current .current.toctree-l2>ul,.wy-menu-vertical .toctree-l2.current .current.toctree-l3>ul,.wy-menu-vertical .toctree-l3.current .current.toctree-l4>ul,.wy-menu-vertical .toctree-l4.current .current.toctree-l5>ul,.wy-menu-vertical .toctree-l5.current .current.toctree-l6>ul,.wy-menu-vertical .toctree-l6.current .current.toctree-l7>ul,.wy-menu-vertical .toctree-l7.current .current.toctree-l8>ul,.wy-menu-vertical .toctree-l8.current .current.toctree-l9>ul,.wy-menu-vertical .toctree-l9.current .current.toctree-l10>ul,.wy-menu-vertical .toctree-l10.current .current.toctree-l11>ul{display:block}.wy-menu-vertical li.toctree-l3,.wy-menu-vertical li.toctree-l4{font-size:.9em}.wy-menu-vertical li.toctree-l2 a,.wy-menu-vertical li.toctree-l3 a,.wy-menu-vertical li.toctree-l4 a,.wy-menu-vertical li.toctree-l5 a,.wy-menu-vertical li.toctree-l6 a,.wy-menu-vertical li.toctree-l7 a,.wy-menu-vertical li.toctree-l8 a,.wy-menu-vertical li.toctree-l9 a,.wy-menu-vertical li.toctree-l10 a{color:#404040}.wy-menu-vertical li.toctree-l2 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l3 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l4 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l5 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l6 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l7 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l8 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l9 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l10 a:hover button.toctree-expand{color:gray}.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a,.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a,.wy-menu-vertical li.toctree-l4.current li.toctree-l5>a,.wy-menu-vertical li.toctree-l5.current li.toctree-l6>a,.wy-menu-vertical li.toctree-l6.current li.toctree-l7>a,.wy-menu-vertical li.toctree-l7.current li.toctree-l8>a,.wy-menu-vertical li.toctree-l8.current li.toctree-l9>a,.wy-menu-vertical li.toctree-l9.current li.toctree-l10>a,.wy-menu-vertical li.toctree-l10.current li.toctree-l11>a{display:block}.wy-menu-vertical li.toctree-l2.current>a{padding:.4045em 2.427em}.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a{padding:.4045em 4.045em;padding-right:1.618em}.wy-menu-vertical li.toctree-l3.current>a{padding:.4045em 4.045em}.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a{padding:.4045em 5.663em;padding-right:1.618em}.wy-menu-vertical li.toctree-l4.current>a{padding:.4045em 5.663em}.wy-menu-vertical li.toctree-l4.current li.toctree-l5>a{padding:.4045em 7.281em;padding-right:1.618em}.wy-menu-vertical li.toctree-l5.current>a{padding:.4045em 7.281em}.wy-menu-vertical li.toctree-l5.current li.toctree-l6>a{padding:.4045em 8.899em;padding-right:1.618em}.wy-menu-vertical li.toctree-l6.current>a{padding:.4045em 8.899em}.wy-menu-vertical li.toctree-l6.current li.toctree-l7>a{padding:.4045em 10.517em;padding-right:1.618em}.wy-menu-vertical li.toctree-l7.current>a{padding:.4045em 10.517em}.wy-menu-vertical li.toctree-l7.current li.toctree-l8>a{padding:.4045em 12.135em;padding-right:1.618em}.wy-menu-vertical li.toctree-l8.current>a{padding:.4045em 12.135em}.wy-menu-vertical li.toctree-l8.current li.toctree-l9>a{padding:.4045em 13.753em;padding-right:1.618em}.wy-menu-vertical li.toctree-l9.current>a{padding:.4045em 13.753em}.wy-menu-vertical li.toctree-l9.current li.toctree-l10>a{padding:.4045em 15.371em;padding-right:1.618em}.wy-menu-vertical li.toctree-l10.current>a{padding:.4045em 15.371em}.wy-menu-vertical li.toctree-l10.current li.toctree-l11>a{padding:.4045em 16.989em;padding-right:1.618em}.wy-menu-vertical li.toctree-l2.current>a{background:#c9c9c9}.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a{background:#c9c9c9}.wy-menu-vertical li.toctree-l2 button.toctree-expand{color:#a3a3a3}.wy-menu-vertical li.toctree-l3.current>a{background:#bdbdbd}.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a{background:#bdbdbd}.wy-menu-vertical li.toctree-l3 button.toctree-expand{color:#969696}.wy-menu-vertical li.current ul{display:block}.wy-menu-vertical li ul{margin-bottom:0;display:none}.wy-menu-vertical li ul li a{margin-bottom:0;color:#d9d9d9;font-weight:normal}.wy-menu-vertical a{line-height:18px;padding:.4045em 1.618em;display:block;position:relative;font-size:90%;color:#d9d9d9}.wy-menu-vertical a:hover{background-color:#4e4a4a;cursor:pointer}.wy-menu-vertical a:hover button.toctree-expand{color:#d9d9d9}.wy-menu-vertical a:active{background-color:#2980B9;cursor:pointer;color:#fff}.wy-menu-vertical a:active button.toctree-expand{color:#fff}.wy-side-nav-search{display:block;width:300px;padding:.809em;margin-bottom:.809em;z-index:200;background-color:#2980B9;text-align:center;color:#fcfcfc}.wy-side-nav-search input[type=text]{width:100%;border-radius:50px;padding:6px 12px;border-color:#2472a4}.wy-side-nav-search img{display:block;margin:auto auto .809em auto;height:45px;width:45px;background-color:#2980B9;padding:5px;border-radius:100%}.wy-side-nav-search>a,.wy-side-nav-search .wy-dropdown>a{color:#fcfcfc;font-size:100%;font-weight:bold;display:inline-block;padding:4px 6px;margin-bottom:.809em;max-width:100%}.wy-side-nav-search>a:hover,.wy-side-nav-search .wy-dropdown>a:hover{background:rgba(255,255,255,0.1)}.wy-side-nav-search>a img.logo,.wy-side-nav-search .wy-dropdown>a img.logo{display:block;margin:0 auto;height:auto;width:auto;border-radius:0;max-width:100%;background:transparent}.wy-side-nav-search>a.icon img.logo,.wy-side-nav-search .wy-dropdown>a.icon img.logo{margin-top:.85em}.wy-side-nav-search>div.version{margin-top:-.4045em;margin-bottom:.809em;font-weight:normal;color:rgba(255,255,255,0.3)}.wy-nav .wy-menu-vertical header{color:#2980B9}.wy-nav .wy-menu-vertical a{color:#b3b3b3}.wy-nav .wy-menu-vertical a:hover{background-color:#2980B9;color:#fff}[data-menu-wrap]{-webkit-transition:all .2s ease-in;-moz-transition:all .2s ease-in;transition:all .2s ease-in;position:absolute;opacity:1;width:100%;opacity:0}[data-menu-wrap].move-center{left:0;right:auto;opacity:1}[data-menu-wrap].move-left{right:auto;left:-100%;opacity:0}[data-menu-wrap].move-right{right:-100%;left:auto;opacity:0}.wy-body-for-nav{background:#fcfcfc}.wy-grid-for-nav{position:absolute;width:100%;height:100%}.wy-nav-side{position:fixed;top:0;bottom:0;left:0;padding-bottom:2em;width:300px;overflow-x:hidden;overflow-y:hidden;min-height:100%;color:#9b9b9b;background:#343131;z-index:200}.wy-side-scroll{width:320px;position:relative;overflow-x:hidden;overflow-y:scroll;height:100%}.wy-nav-top{display:none;background:#2980B9;color:#fff;padding:.4045em .809em;position:relative;line-height:50px;text-align:center;font-size:100%;*zoom:1}.wy-nav-top:before,.wy-nav-top:after{display:table;content:""}.wy-nav-top:after{clear:both}.wy-nav-top a{color:#fff;font-weight:bold}.wy-nav-top img{margin-right:12px;height:45px;width:45px;background-color:#2980B9;padding:5px;border-radius:100%}.wy-nav-top i{font-size:30px;float:left;cursor:pointer;padding-top:inherit}.wy-nav-content-wrap{margin-left:300px;background:#fcfcfc;min-height:100%}.wy-nav-content{padding:1.618em 3.236em;height:100%;max-width:800px;margin:auto}.wy-body-mask{position:fixed;width:100%;height:100%;background:rgba(0,0,0,0.2);display:none;z-index:499}.wy-body-mask.on{display:block}footer{color:gray}footer p{margin-bottom:12px}footer span.commit code,footer span.commit .rst-content tt,.rst-content footer span.commit tt{padding:0px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;font-size:1em;background:none;border:none;color:gray}.rst-footer-buttons{*zoom:1}.rst-footer-buttons:before,.rst-footer-buttons:after{width:100%}.rst-footer-buttons:before,.rst-footer-buttons:after{display:table;content:""}.rst-footer-buttons:after{clear:both}.rst-breadcrumbs-buttons{margin-top:12px;*zoom:1}.rst-breadcrumbs-buttons:before,.rst-breadcrumbs-buttons:after{display:table;content:""}.rst-breadcrumbs-buttons:after{clear:both}#search-results .search li{margin-bottom:24px;border-bottom:solid 1px #e1e4e5;padding-bottom:24px}#search-results .search li:first-child{border-top:solid 1px #e1e4e5;padding-top:24px}#search-results .search li a{font-size:120%;margin-bottom:12px;display:inline-block}#search-results .context{color:gray;font-size:90%}.genindextable li>ul{margin-left:24px}@media screen and (max-width: 768px){.wy-body-for-nav{background:#fcfcfc}.wy-nav-top{display:block}.wy-nav-side{left:-300px}.wy-nav-side.shift{width:85%;left:0}.wy-side-scroll{width:auto}.wy-side-nav-search{width:auto}.wy-menu.wy-menu-vertical{width:auto}.wy-nav-content-wrap{margin-left:0}.wy-nav-content-wrap .wy-nav-content{padding:1.618em}.wy-nav-content-wrap.shift{position:fixed;min-width:100%;left:85%;top:0;height:100%;overflow:hidden}}@media screen and (min-width: 1100px){.wy-nav-content-wrap{background:rgba(0,0,0,0.05)}.wy-nav-content{margin:0;background:#fcfcfc}}@media print{.rst-versions,footer,.wy-nav-side{display:none}.wy-nav-content-wrap{margin-left:0}}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:"Lato","proxima-nova","Helvetica Neue",Arial,sans-serif;z-index:400}.rst-versions a{color:#2980B9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27AE60;*zoom:1}.rst-versions .rst-current-version:before,.rst-versions .rst-current-version:after{display:table;content:""}.rst-versions .rst-current-version:after{clear:both}.rst-versions .rst-current-version .fa,.rst-versions .rst-current-version .wy-menu-vertical li button.toctree-expand,.wy-menu-vertical li .rst-versions .rst-current-version button.toctree-expand,.rst-versions .rst-current-version .rst-content .admonition-title,.rst-content .rst-versions .rst-current-version .admonition-title,.rst-versions .rst-current-version .rst-content h1 .headerlink,.rst-content h1 .rst-versions .rst-current-version .headerlink,.rst-versions .rst-current-version .rst-content h2 .headerlink,.rst-content h2 .rst-versions .rst-current-version .headerlink,.rst-versions .rst-current-version .rst-content h3 .headerlink,.rst-content h3 .rst-versions .rst-current-version .headerlink,.rst-versions .rst-current-version .rst-content h4 .headerlink,.rst-content h4 .rst-versions .rst-current-version .headerlink,.rst-versions .rst-current-version .rst-content h5 .headerlink,.rst-content h5 .rst-versions .rst-current-version .headerlink,.rst-versions .rst-current-version .rst-content h6 .headerlink,.rst-content h6 .rst-versions .rst-current-version .headerlink,.rst-versions .rst-current-version .rst-content dl dt .headerlink,.rst-content dl dt .rst-versions .rst-current-version .headerlink,.rst-versions .rst-current-version .rst-content p .headerlink,.rst-content p .rst-versions .rst-current-version .headerlink,.rst-versions .rst-current-version .rst-content table>caption .headerlink,.rst-content table>caption .rst-versions .rst-current-version .headerlink,.rst-versions .rst-current-version .rst-content .code-block-caption .headerlink,.rst-content .code-block-caption .rst-versions .rst-current-version .headerlink,.rst-versions .rst-current-version .rst-content .eqno .headerlink,.rst-content .eqno .rst-versions .rst-current-version .headerlink,.rst-versions .rst-current-version .rst-content tt.download span:first-child,.rst-content tt.download .rst-versions .rst-current-version span:first-child,.rst-versions .rst-current-version .rst-content code.download span:first-child,.rst-content code.download .rst-versions .rst-current-version span:first-child,.rst-versions .rst-current-version .icon{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#E74C3C;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#F1C40F;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:gray;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:solid 1px #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width: 768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}}.rst-content h1,.rst-content h2,.rst-content .toctree-wrapper>p.caption,.rst-content h3,.rst-content h4,.rst-content h5,.rst-content h6{margin-bottom:24px}.rst-content img{max-width:100%;height:auto}.rst-content div.figure,.rst-content figure{margin-bottom:24px}.rst-content div.figure .caption-text,.rst-content figure .caption-text{font-style:italic}.rst-content div.figure p:last-child.caption,.rst-content figure p:last-child.caption{margin-bottom:0px}.rst-content div.figure.align-center,.rst-content figure.align-center{text-align:center}.rst-content .section>img,.rst-content .section>a>img,.rst-content section>img,.rst-content section>a>img{margin-bottom:24px}.rst-content abbr[title]{text-decoration:none}.rst-content.style-external-links a.reference.external:after{font-family:FontAwesome;content:"";color:#b3b3b3;vertical-align:super;font-size:60%;margin:0 .2em}.rst-content blockquote{margin-left:24px;line-height:24px;margin-bottom:24px}.rst-content pre.literal-block{white-space:pre;margin:0;padding:12px 12px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;display:block;overflow:auto}.rst-content pre.literal-block,.rst-content div[class^='highlight']{border:1px solid #e1e4e5;overflow-x:auto;margin:1px 0 24px 0}.rst-content pre.literal-block div[class^='highlight'],.rst-content div[class^='highlight'] div[class^='highlight']{padding:0px;border:none;margin:0}.rst-content div[class^='highlight'] td.code{width:100%}.rst-content .linenodiv pre{border-right:solid 1px #e6e9ea;margin:0;padding:12px 12px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;user-select:none;pointer-events:none}.rst-content div[class^='highlight'] pre{white-space:pre;margin:0;padding:12px 12px;display:block;overflow:auto}.rst-content div[class^='highlight'] pre .hll{display:block;margin:0 -12px;padding:0 12px}.rst-content pre.literal-block,.rst-content div[class^='highlight'] pre,.rst-content .linenodiv pre{font-family:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;font-size:12px;line-height:1.4}.rst-content div.highlight span.linenos,.rst-content div.highlight .gp{user-select:none;pointer-events:none}.rst-content div.highlight span.linenos{display:inline-block;padding-left:0px;padding-right:12px;margin-right:12px;border-right:1px solid #e6e9ea}.rst-content .code-block-caption{font-style:italic;font-size:85%;line-height:1;padding:1em 0;text-align:center}@media print{.rst-content .codeblock,.rst-content div[class^='highlight'],.rst-content div[class^='highlight'] pre{white-space:pre-wrap}}.rst-content .note,.rst-content .attention,.rst-content .caution,.rst-content .danger,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .tip,.rst-content .warning,.rst-content .seealso,.rst-content .admonition-todo,.rst-content .admonition{clear:both}.rst-content .note .last,.rst-content .note>*:last-child,.rst-content .attention .last,.rst-content .attention>*:last-child,.rst-content .caution .last,.rst-content .caution>*:last-child,.rst-content .danger .last,.rst-content .danger>*:last-child,.rst-content .error .last,.rst-content .error>*:last-child,.rst-content .hint .last,.rst-content .hint>*:last-child,.rst-content .important .last,.rst-content .important>*:last-child,.rst-content .tip .last,.rst-content .tip>*:last-child,.rst-content .warning .last,.rst-content .warning>*:last-child,.rst-content .seealso .last,.rst-content .seealso>*:last-child,.rst-content .admonition-todo .last,.rst-content .admonition-todo>*:last-child,.rst-content .admonition .last,.rst-content .admonition>*:last-child{margin-bottom:0}.rst-content .admonition-title:before{margin-right:4px}.rst-content .admonition table{border-color:rgba(0,0,0,0.1)}.rst-content .admonition table td,.rst-content .admonition table th{background:transparent !important;border-color:rgba(0,0,0,0.1) !important}.rst-content .section ol.loweralpha,.rst-content .section ol.loweralpha>li,.rst-content section ol.loweralpha,.rst-content section ol.loweralpha>li,.rst-content .toctree-wrapper ol.loweralpha,.rst-content .toctree-wrapper ol.loweralpha>li{list-style:lower-alpha}.rst-content .section ol.upperalpha,.rst-content .section ol.upperalpha>li,.rst-content section ol.upperalpha,.rst-content section ol.upperalpha>li,.rst-content .toctree-wrapper ol.upperalpha,.rst-content .toctree-wrapper ol.upperalpha>li{list-style:upper-alpha}.rst-content .section ol li>*,.rst-content .section ul li>*,.rst-content section ol li>*,.rst-content section ul li>*,.rst-content .toctree-wrapper ol li>*,.rst-content .toctree-wrapper ul li>*{margin-top:12px;margin-bottom:12px}.rst-content .section ol li>*:first-child,.rst-content .section ul li>*:first-child,.rst-content section ol li>*:first-child,.rst-content section ul li>*:first-child,.rst-content .toctree-wrapper ol li>*:first-child,.rst-content .toctree-wrapper ul li>*:first-child{margin-top:0rem}.rst-content .section ol li>p,.rst-content .section ol li>p:last-child,.rst-content .section ul li>p,.rst-content .section ul li>p:last-child,.rst-content section ol li>p,.rst-content section ol li>p:last-child,.rst-content section ul li>p,.rst-content section ul li>p:last-child,.rst-content .toctree-wrapper ol li>p,.rst-content .toctree-wrapper ol li>p:last-child,.rst-content .toctree-wrapper ul li>p,.rst-content .toctree-wrapper ul li>p:last-child{margin-bottom:12px}.rst-content .section ol li>p:only-child,.rst-content .section ol li>p:only-child:last-child,.rst-content .section ul li>p:only-child,.rst-content .section ul li>p:only-child:last-child,.rst-content section ol li>p:only-child,.rst-content section ol li>p:only-child:last-child,.rst-content section ul li>p:only-child,.rst-content section ul li>p:only-child:last-child,.rst-content .toctree-wrapper ol li>p:only-child,.rst-content .toctree-wrapper ol li>p:only-child:last-child,.rst-content .toctree-wrapper ul li>p:only-child,.rst-content .toctree-wrapper ul li>p:only-child:last-child{margin-bottom:0rem}.rst-content .section ol li>ul,.rst-content .section ol li>ol,.rst-content .section ul li>ul,.rst-content .section ul li>ol,.rst-content section ol li>ul,.rst-content section ol li>ol,.rst-content section ul li>ul,.rst-content section ul li>ol,.rst-content .toctree-wrapper ol li>ul,.rst-content .toctree-wrapper ol li>ol,.rst-content .toctree-wrapper ul li>ul,.rst-content .toctree-wrapper ul li>ol{margin-bottom:12px}.rst-content .section ol.simple li>*,.rst-content .section ul.simple li>*,.rst-content section ol.simple li>*,.rst-content section ul.simple li>*,.rst-content .toctree-wrapper ol.simple li>*,.rst-content .toctree-wrapper ul.simple li>*{margin-top:0rem;margin-bottom:0rem}.rst-content .section ol.simple li ul,.rst-content .section ol.simple li ol,.rst-content .section ul.simple li ul,.rst-content .section ul.simple li ol,.rst-content section ol.simple li ul,.rst-content section ol.simple li ol,.rst-content section ul.simple li ul,.rst-content section ul.simple li ol,.rst-content .toctree-wrapper ol.simple li ul,.rst-content .toctree-wrapper ol.simple li ol,.rst-content .toctree-wrapper ul.simple li ul,.rst-content .toctree-wrapper ul.simple li ol{margin-top:0rem;margin-bottom:0rem}.rst-content .line-block{margin-left:0px;margin-bottom:24px;line-height:24px}.rst-content .line-block .line-block{margin-left:24px;margin-bottom:0px}.rst-content .topic-title{font-weight:bold;margin-bottom:12px}.rst-content .toc-backref{color:#404040}.rst-content .align-right{float:right;margin:0px 0px 24px 24px}.rst-content .align-left{float:left;margin:0px 24px 24px 0px}.rst-content .align-center{margin:auto}.rst-content .align-center:not(table){display:block}.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content .toctree-wrapper>p.caption .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content dl dt .headerlink,.rst-content p .headerlink,.rst-content p.caption .headerlink,.rst-content table>caption .headerlink,.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink{opacity:0;font-size:14px;font-family:FontAwesome;margin-left:.5em}.rst-content h1 .headerlink:focus,.rst-content h2 .headerlink:focus,.rst-content .toctree-wrapper>p.caption .headerlink:focus,.rst-content h3 .headerlink:focus,.rst-content h4 .headerlink:focus,.rst-content h5 .headerlink:focus,.rst-content h6 .headerlink:focus,.rst-content dl dt .headerlink:focus,.rst-content p .headerlink:focus,.rst-content p.caption .headerlink:focus,.rst-content table>caption .headerlink:focus,.rst-content .code-block-caption .headerlink:focus,.rst-content .eqno .headerlink:focus{opacity:1}.rst-content h1:hover .headerlink,.rst-content h2:hover .headerlink,.rst-content .toctree-wrapper>p.caption:hover .headerlink,.rst-content h3:hover .headerlink,.rst-content h4:hover .headerlink,.rst-content h5:hover .headerlink,.rst-content h6:hover .headerlink,.rst-content dl dt:hover .headerlink,.rst-content p:hover .headerlink,.rst-content p.caption:hover .headerlink,.rst-content table>caption:hover .headerlink,.rst-content .code-block-caption:hover .headerlink,.rst-content .eqno:hover .headerlink{opacity:1}.rst-content .btn:focus{outline:2px solid}.rst-content table>caption .headerlink:after{font-size:12px}.rst-content .centered{text-align:center}.rst-content .sidebar{float:right;width:40%;display:block;margin:0 0 24px 24px;padding:24px;background:#f3f6f6;border:solid 1px #e1e4e5}.rst-content .sidebar p,.rst-content .sidebar ul,.rst-content .sidebar dl{font-size:90%}.rst-content .sidebar .last,.rst-content .sidebar>*:last-child{margin-bottom:0}.rst-content .sidebar .sidebar-title{display:block;font-family:"Roboto Slab","ff-tisa-web-pro","Georgia",Arial,sans-serif;font-weight:bold;background:#e1e4e5;padding:6px 12px;margin:-24px;margin-bottom:24px;font-size:100%}.rst-content .highlighted{background:#F1C40F;box-shadow:0 0 0 2px #F1C40F;display:inline;font-weight:bold}.rst-content .footnote-reference,.rst-content .citation-reference{vertical-align:baseline;position:relative;top:-0.4em;line-height:0;font-size:90%}.rst-content .hlist{width:100%}.rst-content dl dt span.classifier:before{content:" : "}.rst-content dl dt span.classifier-delimiter{display:none !important}html.writer-html4 .rst-content table.docutils.citation,html.writer-html4 .rst-content table.docutils.footnote{background:none;border:none}html.writer-html4 .rst-content table.docutils.citation td,html.writer-html4 .rst-content table.docutils.citation tr,html.writer-html4 .rst-content table.docutils.footnote td,html.writer-html4 .rst-content table.docutils.footnote tr{border:none;background-color:transparent !important;white-space:normal}html.writer-html4 .rst-content table.docutils.citation td.label,html.writer-html4 .rst-content table.docutils.footnote td.label{padding-left:0;padding-right:0;vertical-align:top}html.writer-html5 .rst-content dl.footnote,html.writer-html5 .rst-content dl.field-list{display:grid;grid-template-columns:max-content auto}html.writer-html5 .rst-content dl.footnote>dt,html.writer-html5 .rst-content dl.field-list>dt{padding-left:1rem}html.writer-html5 .rst-content dl.footnote>dt:after,html.writer-html5 .rst-content dl.field-list>dt:after{content:":"}html.writer-html5 .rst-content dl.footnote>dt,html.writer-html5 .rst-content dl.footnote>dd,html.writer-html5 .rst-content dl.field-list>dt,html.writer-html5 .rst-content dl.field-list>dd{margin-bottom:0rem}html.writer-html5 .rst-content dl.footnote{font-size:.9rem}html.writer-html5 .rst-content dl.footnote>dt{margin:0rem .5rem .5rem 0rem;line-height:1.2rem;word-break:break-all;font-weight:normal}html.writer-html5 .rst-content dl.footnote>dt>span.brackets{margin-right:.5rem}html.writer-html5 .rst-content dl.footnote>dt>span.brackets:before{content:"["}html.writer-html5 .rst-content dl.footnote>dt>span.brackets:after{content:"]"}html.writer-html5 .rst-content dl.footnote>dt>span.fn-backref{font-style:italic}html.writer-html5 .rst-content dl.footnote>dd{margin:0rem 0rem .5rem 0rem;line-height:1.2rem}html.writer-html5 .rst-content dl.footnote>dd p{font-size:.9rem}html.writer-html5 .rst-content dl.option-list kbd{font-size:.9rem}html.writer-html4 .rst-content table.docutils.citation,.rst-content table.docutils.footnote,html.writer-html5 .rst-content dl.footnote{color:gray}html.writer-html4 .rst-content table.docutils.citation tt,html.writer-html4 .rst-content table.docutils.citation code,.rst-content table.docutils.footnote tt,.rst-content table.docutils.footnote code,html.writer-html5 .rst-content dl.footnote tt,html.writer-html5 .rst-content dl.footnote code{color:#555}.rst-content .wy-table-responsive.citation,.rst-content .wy-table-responsive.footnote{margin-bottom:0}.rst-content .wy-table-responsive.citation+:not(.citation),.rst-content .wy-table-responsive.footnote+:not(.footnote){margin-top:24px}.rst-content .wy-table-responsive.citation:last-child,.rst-content .wy-table-responsive.footnote:last-child{margin-bottom:24px}.rst-content table.docutils th{border-color:#e1e4e5}html.writer-html5 .rst-content table.docutils th{border:1px solid #e1e4e5}html.writer-html5 .rst-content table.docutils th>p,html.writer-html5 .rst-content table.docutils td>p{line-height:1rem;margin-bottom:0rem;font-size:.9rem}.rst-content table.docutils td .last,.rst-content table.docutils td .last>*:last-child{margin-bottom:0}.rst-content table.field-list{border:none}.rst-content table.field-list td{border:none}.rst-content table.field-list td p{font-size:inherit;line-height:inherit}.rst-content table.field-list td>strong{display:inline-block}.rst-content table.field-list .field-name{padding-right:10px;text-align:left;white-space:nowrap}.rst-content table.field-list .field-body{text-align:left}.rst-content tt,.rst-content tt,.rst-content code{color:#000;font-family:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;padding:2px 5px}.rst-content tt big,.rst-content tt em,.rst-content tt big,.rst-content code big,.rst-content tt em,.rst-content code em{font-size:100% !important;line-height:normal}.rst-content tt.literal,.rst-content tt.literal,.rst-content code.literal{color:#E74C3C;white-space:normal}.rst-content tt.xref,a .rst-content tt,.rst-content tt.xref,.rst-content code.xref,a .rst-content tt,a .rst-content code{font-weight:bold;color:#404040}.rst-content pre,.rst-content kbd,.rst-content samp{font-family:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace}.rst-content a tt,.rst-content a tt,.rst-content a code{color:#2980B9}.rst-content dl{margin-bottom:24px}.rst-content dl dt{font-weight:bold;margin-bottom:12px}.rst-content dl p,.rst-content dl table,.rst-content dl ul,.rst-content dl ol{margin-bottom:12px}.rst-content dl dd{margin:0 0 12px 24px;line-height:24px}html.writer-html4 .rst-content dl:not(.docutils),html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple){margin-bottom:24px}html.writer-html4 .rst-content dl:not(.docutils)>dt,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple)>dt{display:table;margin:6px 0;font-size:90%;line-height:normal;background:#e7f2fa;color:#2980B9;border-top:solid 3px #6ab0de;padding:6px;position:relative}html.writer-html4 .rst-content dl:not(.docutils)>dt:before,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple)>dt:before{color:#6ab0de}html.writer-html4 .rst-content dl:not(.docutils)>dt .headerlink,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple)>dt .headerlink{color:#404040;font-size:100% !important}html.writer-html4 .rst-content dl:not(.docutils) dl:not(.field-list)>dt,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) dl:not(.field-list)>dt{margin-bottom:6px;border:none;border-left:solid 3px #ccc;background:#f0f0f0;color:#555}html.writer-html4 .rst-content dl:not(.docutils) dl:not(.field-list)>dt .headerlink,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) dl:not(.field-list)>dt .headerlink{color:#404040;font-size:100% !important}html.writer-html4 .rst-content dl:not(.docutils)>dt:first-child,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple)>dt:first-child{margin-top:0}html.writer-html4 .rst-content dl:not(.docutils) tt.descname,html.writer-html4 .rst-content dl:not(.docutils) tt.descclassname,html.writer-html4 .rst-content dl:not(.docutils) tt.descname,html.writer-html4 .rst-content dl:not(.docutils) code.descname,html.writer-html4 .rst-content dl:not(.docutils) tt.descclassname,html.writer-html4 .rst-content dl:not(.docutils) code.descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) tt.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) tt.descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) tt.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) code.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) tt.descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) code.descclassname{background-color:transparent;border:none;padding:0;font-size:100% !important}html.writer-html4 .rst-content dl:not(.docutils) tt.descname,html.writer-html4 .rst-content dl:not(.docutils) tt.descname,html.writer-html4 .rst-content dl:not(.docutils) code.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) tt.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) tt.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) code.descname{font-weight:bold}html.writer-html4 .rst-content dl:not(.docutils) .optional,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .optional{display:inline-block;padding:0 4px;color:#000;font-weight:bold}html.writer-html4 .rst-content dl:not(.docutils) .property,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .property{display:inline-block;padding-right:8px;max-width:100%}html.writer-html4 .rst-content dl:not(.docutils) .k,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .k{font-style:italic}html.writer-html4 .rst-content dl:not(.docutils) .sig-name,html.writer-html4 .rst-content dl:not(.docutils) .descname,html.writer-html4 .rst-content dl:not(.docutils) .descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .sig-name,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .descclassname{font-family:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;color:#000}.rst-content .viewcode-link,.rst-content .viewcode-back{display:inline-block;color:#27AE60;font-size:80%;padding-left:24px}.rst-content .viewcode-back{display:block;float:right}.rst-content p.rubric{margin-bottom:12px;font-weight:bold}.rst-content tt.download,.rst-content code.download{background:inherit;padding:inherit;font-weight:normal;font-family:inherit;font-size:inherit;color:inherit;border:inherit;white-space:inherit}.rst-content tt.download span:first-child,.rst-content code.download span:first-child{-webkit-font-smoothing:subpixel-antialiased}.rst-content tt.download span:first-child:before,.rst-content code.download span:first-child:before{margin-right:4px}.rst-content .guilabel{border:1px solid #7fbbe3;background:#e7f2fa;font-size:80%;font-weight:700;border-radius:4px;padding:2.4px 6px;margin:auto 2px}.rst-content .versionmodified{font-style:italic}@media screen and (max-width: 480px){.rst-content .sidebar{width:100%}}span[id*='MathJax-Span']{color:#404040}.math{text-align:center}@font-face{font-family:"Lato";src:url("../fonts/Lato-Regular.woff2") format("woff2"),url("../fonts/Lato-Regular.ttf") format("truetype");font-weight:400;font-style:normal;font-display:block}@font-face{font-family:"Lato";src:url("../fonts/Lato-Bold.woff2") format("woff2"),url("../fonts/Lato-Bold.ttf") format("truetype");font-weight:700;font-style:normal;font-display:block}@font-face{font-family:"Lato";src:url("../fonts/Lato-BoldItalic.woff2") format("woff2"),url("../fonts/Lato-BoldItalic.ttf") format("truetype");font-weight:700;font-style:italic;font-display:block}@font-face{font-family:"Lato";src:url("../fonts/Lato-Italic.woff2") format("woff2"),url("../fonts/Lato-Italic.ttf") format("truetype");font-weight:400;font-style:italic;font-display:block}@font-face{font-family:"Roboto Slab";font-style:normal;font-weight:400;src:url("../fonts/RobotoSlab-Regular.woff2") format("woff2");font-display:block}@font-face{font-family:"Roboto Slab";font-style:normal;font-weight:700;src:url("../fonts/RobotoSlab-Bold.woff2") format("woff2");font-display:block} diff --git a/_static/doctools.js b/_static/doctools.js new file mode 100644 index 0000000..8cbf1b1 --- /dev/null +++ b/_static/doctools.js @@ -0,0 +1,323 @@ +/* + * doctools.js + * ~~~~~~~~~~~ + * + * Sphinx JavaScript utilities for all documentation. + * + * :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/** + * select a different prefix for underscore + */ +$u = _.noConflict(); + +/** + * make the code below compatible with browsers without + * an installed firebug like debugger +if (!window.console || !console.firebug) { + var names = ["log", "debug", "info", "warn", "error", "assert", "dir", + "dirxml", "group", "groupEnd", "time", "timeEnd", "count", "trace", + "profile", "profileEnd"]; + window.console = {}; + for (var i = 0; i < names.length; ++i) + window.console[names[i]] = function() {}; +} + */ + +/** + * small helper function to urldecode strings + * + * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL + */ +jQuery.urldecode = function(x) { + if (!x) { + return x + } + return decodeURIComponent(x.replace(/\+/g, ' ')); +}; + +/** + * small helper function to urlencode strings + */ +jQuery.urlencode = encodeURIComponent; + +/** + * This function returns the parsed url parameters of the + * current request. Multiple values per key are supported, + * it will always return arrays of strings for the value parts. + */ +jQuery.getQueryParameters = function(s) { + if (typeof s === 'undefined') + s = document.location.search; + var parts = s.substr(s.indexOf('?') + 1).split('&'); + var result = {}; + for (var i = 0; i < parts.length; i++) { + var tmp = parts[i].split('=', 2); + var key = jQuery.urldecode(tmp[0]); + var value = jQuery.urldecode(tmp[1]); + if (key in result) + result[key].push(value); + else + result[key] = [value]; + } + return result; +}; + +/** + * highlight a given string on a jquery object by wrapping it in + * span elements with the given class name. + */ +jQuery.fn.highlightText = function(text, className) { + function highlight(node, addItems) { + if (node.nodeType === 3) { + var val = node.nodeValue; + var pos = val.toLowerCase().indexOf(text); + if (pos >= 0 && + !jQuery(node.parentNode).hasClass(className) && + !jQuery(node.parentNode).hasClass("nohighlight")) { + var span; + var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg"); + if (isInSVG) { + span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); + } else { + span = document.createElement("span"); + span.className = className; + } + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + node.parentNode.insertBefore(span, node.parentNode.insertBefore( + document.createTextNode(val.substr(pos + text.length)), + node.nextSibling)); + node.nodeValue = val.substr(0, pos); + if (isInSVG) { + var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect"); + var bbox = node.parentElement.getBBox(); + rect.x.baseVal.value = bbox.x; + rect.y.baseVal.value = bbox.y; + rect.width.baseVal.value = bbox.width; + rect.height.baseVal.value = bbox.height; + rect.setAttribute('class', className); + addItems.push({ + "parent": node.parentNode, + "target": rect}); + } + } + } + else if (!jQuery(node).is("button, select, textarea")) { + jQuery.each(node.childNodes, function() { + highlight(this, addItems); + }); + } + } + var addItems = []; + var result = this.each(function() { + highlight(this, addItems); + }); + for (var i = 0; i < addItems.length; ++i) { + jQuery(addItems[i].parent).before(addItems[i].target); + } + return result; +}; + +/* + * backward compatibility for jQuery.browser + * This will be supported until firefox bug is fixed. + */ +if (!jQuery.browser) { + jQuery.uaMatch = function(ua) { + ua = ua.toLowerCase(); + + var match = /(chrome)[ \/]([\w.]+)/.exec(ua) || + /(webkit)[ \/]([\w.]+)/.exec(ua) || + /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) || + /(msie) ([\w.]+)/.exec(ua) || + ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) || + []; + + return { + browser: match[ 1 ] || "", + version: match[ 2 ] || "0" + }; + }; + jQuery.browser = {}; + jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true; +} + +/** + * Small JavaScript module for the documentation. + */ +var Documentation = { + + init : function() { + this.fixFirefoxAnchorBug(); + this.highlightSearchWords(); + this.initIndexTable(); + if (DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) { + this.initOnKeyListeners(); + } + }, + + /** + * i18n support + */ + TRANSLATIONS : {}, + PLURAL_EXPR : function(n) { return n === 1 ? 0 : 1; }, + LOCALE : 'unknown', + + // gettext and ngettext don't access this so that the functions + // can safely bound to a different name (_ = Documentation.gettext) + gettext : function(string) { + var translated = Documentation.TRANSLATIONS[string]; + if (typeof translated === 'undefined') + return string; + return (typeof translated === 'string') ? translated : translated[0]; + }, + + ngettext : function(singular, plural, n) { + var translated = Documentation.TRANSLATIONS[singular]; + if (typeof translated === 'undefined') + return (n == 1) ? singular : plural; + return translated[Documentation.PLURALEXPR(n)]; + }, + + addTranslations : function(catalog) { + for (var key in catalog.messages) + this.TRANSLATIONS[key] = catalog.messages[key]; + this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')'); + this.LOCALE = catalog.locale; + }, + + /** + * add context elements like header anchor links + */ + addContextElements : function() { + $('div[id] > :header:first').each(function() { + $('\u00B6'). + attr('href', '#' + this.id). + attr('title', _('Permalink to this headline')). + appendTo(this); + }); + $('dt[id]').each(function() { + $('\u00B6'). + attr('href', '#' + this.id). + attr('title', _('Permalink to this definition')). + appendTo(this); + }); + }, + + /** + * workaround a firefox stupidity + * see: https://bugzilla.mozilla.org/show_bug.cgi?id=645075 + */ + fixFirefoxAnchorBug : function() { + if (document.location.hash && $.browser.mozilla) + window.setTimeout(function() { + document.location.href += ''; + }, 10); + }, + + /** + * highlight the search words provided in the url in the text + */ + highlightSearchWords : function() { + var params = $.getQueryParameters(); + var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : []; + if (terms.length) { + var body = $('div.body'); + if (!body.length) { + body = $('body'); + } + window.setTimeout(function() { + $.each(terms, function() { + body.highlightText(this.toLowerCase(), 'highlighted'); + }); + }, 10); + $('

' + _('Hide Search Matches') + '

') + .appendTo($('#searchbox')); + } + }, + + /** + * init the domain index toggle buttons + */ + initIndexTable : function() { + var togglers = $('img.toggler').click(function() { + var src = $(this).attr('src'); + var idnum = $(this).attr('id').substr(7); + $('tr.cg-' + idnum).toggle(); + if (src.substr(-9) === 'minus.png') + $(this).attr('src', src.substr(0, src.length-9) + 'plus.png'); + else + $(this).attr('src', src.substr(0, src.length-8) + 'minus.png'); + }).css('display', ''); + if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) { + togglers.click(); + } + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords : function() { + $('#searchbox .highlight-link').fadeOut(300); + $('span.highlighted').removeClass('highlighted'); + }, + + /** + * make the url absolute + */ + makeURL : function(relativeURL) { + return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL; + }, + + /** + * get the current relative url + */ + getCurrentURL : function() { + var path = document.location.pathname; + var parts = path.split(/\//); + $.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() { + if (this === '..') + parts.pop(); + }); + var url = parts.join('/'); + return path.substring(url.lastIndexOf('/') + 1, path.length - 1); + }, + + initOnKeyListeners: function() { + $(document).keydown(function(event) { + var activeElementType = document.activeElement.tagName; + // don't navigate when in search box, textarea, dropdown or button + if (activeElementType !== 'TEXTAREA' && activeElementType !== 'INPUT' && activeElementType !== 'SELECT' + && activeElementType !== 'BUTTON' && !event.altKey && !event.ctrlKey && !event.metaKey + && !event.shiftKey) { + switch (event.keyCode) { + case 37: // left + var prevHref = $('link[rel="prev"]').prop('href'); + if (prevHref) { + window.location.href = prevHref; + return false; + } + break; + case 39: // right + var nextHref = $('link[rel="next"]').prop('href'); + if (nextHref) { + window.location.href = nextHref; + return false; + } + break; + } + } + }); + } +}; + +// quick alias for translations +_ = Documentation.gettext; + +$(document).ready(function() { + Documentation.init(); +}); diff --git a/_static/documentation_options.js b/_static/documentation_options.js new file mode 100644 index 0000000..658880a --- /dev/null +++ b/_static/documentation_options.js @@ -0,0 +1,12 @@ +var DOCUMENTATION_OPTIONS = { + URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'), + VERSION: '3.16.99-rc2', + LANGUAGE: 'None', + COLLAPSE_INDEX: false, + BUILDER: 'html', + FILE_SUFFIX: '.html', + LINK_SUFFIX: '.html', + HAS_SOURCE: true, + SOURCELINK_SUFFIX: '.txt', + NAVIGATION_WITH_KEYS: false +}; \ No newline at end of file diff --git a/_static/file.png b/_static/file.png new file mode 100644 index 0000000..a858a41 Binary files /dev/null and b/_static/file.png differ diff --git a/_static/fonts/Lato-Bold.ttf b/_static/fonts/Lato-Bold.ttf new file mode 100644 index 0000000..70c4dd9 Binary files /dev/null and b/_static/fonts/Lato-Bold.ttf differ diff --git a/_static/fonts/Lato-Bold.woff2 b/_static/fonts/Lato-Bold.woff2 new file mode 100644 index 0000000..2ab3f6d Binary files /dev/null and b/_static/fonts/Lato-Bold.woff2 differ diff --git a/_static/fonts/Lato-BoldItalic.ttf b/_static/fonts/Lato-BoldItalic.ttf new file mode 100644 index 0000000..c0e84bc Binary files /dev/null and b/_static/fonts/Lato-BoldItalic.ttf differ diff --git a/_static/fonts/Lato-BoldItalic.woff2 b/_static/fonts/Lato-BoldItalic.woff2 new file mode 100644 index 0000000..3cedab6 Binary files /dev/null and b/_static/fonts/Lato-BoldItalic.woff2 differ diff --git a/_static/fonts/Lato-Italic.ttf b/_static/fonts/Lato-Italic.ttf new file mode 100644 index 0000000..e7a31ce Binary files /dev/null and b/_static/fonts/Lato-Italic.ttf differ diff --git a/_static/fonts/Lato-Italic.woff2 b/_static/fonts/Lato-Italic.woff2 new file mode 100644 index 0000000..005bd62 Binary files /dev/null and b/_static/fonts/Lato-Italic.woff2 differ diff --git a/_static/fonts/Lato-Regular.ttf b/_static/fonts/Lato-Regular.ttf new file mode 100644 index 0000000..b536f95 Binary files /dev/null and b/_static/fonts/Lato-Regular.ttf differ diff --git a/_static/fonts/Lato-Regular.woff2 b/_static/fonts/Lato-Regular.woff2 new file mode 100644 index 0000000..597115a Binary files /dev/null and b/_static/fonts/Lato-Regular.woff2 differ diff --git a/_static/fonts/RobotoSlab-Bold.woff2 b/_static/fonts/RobotoSlab-Bold.woff2 new file mode 100644 index 0000000..40a6cbc Binary files /dev/null and b/_static/fonts/RobotoSlab-Bold.woff2 differ diff --git a/_static/fonts/RobotoSlab-Regular.woff2 b/_static/fonts/RobotoSlab-Regular.woff2 new file mode 100644 index 0000000..d36556f Binary files /dev/null and b/_static/fonts/RobotoSlab-Regular.woff2 differ diff --git a/_static/fonts/fontawesome-webfont.eot b/_static/fonts/fontawesome-webfont.eot new file mode 100644 index 0000000..e9f60ca Binary files /dev/null and b/_static/fonts/fontawesome-webfont.eot differ diff --git a/_static/fonts/fontawesome-webfont.svg b/_static/fonts/fontawesome-webfont.svg new file mode 100644 index 0000000..855c845 --- /dev/null +++ b/_static/fonts/fontawesome-webfont.svg @@ -0,0 +1,2671 @@ + + + + +Created by FontForge 20120731 at Mon Oct 24 17:37:40 2016 + By ,,, +Copyright Dave Gandy 2016. All rights reserved. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/_static/fonts/fontawesome-webfont.ttf b/_static/fonts/fontawesome-webfont.ttf new file mode 100644 index 0000000..35acda2 Binary files /dev/null and b/_static/fonts/fontawesome-webfont.ttf differ diff --git a/_static/fonts/fontawesome-webfont.woff b/_static/fonts/fontawesome-webfont.woff new file mode 100644 index 0000000..400014a Binary files /dev/null and b/_static/fonts/fontawesome-webfont.woff differ diff --git a/_static/fonts/fontawesome-webfont.woff2 b/_static/fonts/fontawesome-webfont.woff2 new file mode 100644 index 0000000..4d13fc6 Binary files /dev/null and b/_static/fonts/fontawesome-webfont.woff2 differ diff --git a/_static/jquery.js b/_static/jquery.js new file mode 100644 index 0000000..624bca8 --- /dev/null +++ b/_static/jquery.js @@ -0,0 +1,10879 @@ +/*! + * jQuery JavaScript Library v3.6.0 + * https://jquery.com/ + * + * Includes Sizzle.js + * https://sizzlejs.com/ + * + * Copyright OpenJS Foundation and other contributors + * Released under the MIT license + * https://jquery.org/license + */ +( function( global, factory ) { + + "use strict"; + + if ( typeof module === "object" && typeof module.exports === "object" ) { + + // For CommonJS and CommonJS-like environments where a proper `window` + // is present, execute the factory and get jQuery. + // For environments that do not have a `window` with a `document` + // (such as Node.js), expose a factory as module.exports. + // This accentuates the need for the creation of a real `window`. + // e.g. var jQuery = require("jquery")(window); + // See ticket #14549 for more info. + module.exports = global.document ? + factory( global, true ) : + function( w ) { + if ( !w.document ) { + throw new Error( "jQuery requires a window with a document" ); + } + return factory( w ); + }; + } else { + factory( global ); + } + +// Pass this if window is not defined yet +} )( typeof window !== "undefined" ? window : this, function( window, noGlobal ) { + +// Edge <= 12 - 13+, Firefox <=18 - 45+, IE 10 - 11, Safari 5.1 - 9+, iOS 6 - 9.1 +// throw exceptions when non-strict code (e.g., ASP.NET 4.5) accesses strict mode +// arguments.callee.caller (trac-13335). But as of jQuery 3.0 (2016), strict mode should be common +// enough that all such attempts are guarded in a try block. +"use strict"; + +var arr = []; + +var getProto = Object.getPrototypeOf; + +var slice = arr.slice; + +var flat = arr.flat ? function( array ) { + return arr.flat.call( array ); +} : function( array ) { + return arr.concat.apply( [], array ); +}; + + +var push = arr.push; + +var indexOf = arr.indexOf; + +var class2type = {}; + +var toString = class2type.toString; + +var hasOwn = class2type.hasOwnProperty; + +var fnToString = hasOwn.toString; + +var ObjectFunctionString = fnToString.call( Object ); + +var support = {}; + +var isFunction = function isFunction( obj ) { + + // Support: Chrome <=57, Firefox <=52 + // In some browsers, typeof returns "function" for HTML elements + // (i.e., `typeof document.createElement( "object" ) === "function"`). + // We don't want to classify *any* DOM node as a function. + // Support: QtWeb <=3.8.5, WebKit <=534.34, wkhtmltopdf tool <=0.12.5 + // Plus for old WebKit, typeof returns "function" for HTML collections + // (e.g., `typeof document.getElementsByTagName("div") === "function"`). (gh-4756) + return typeof obj === "function" && typeof obj.nodeType !== "number" && + typeof obj.item !== "function"; + }; + + +var isWindow = function isWindow( obj ) { + return obj != null && obj === obj.window; + }; + + +var document = window.document; + + + + var preservedScriptAttributes = { + type: true, + src: true, + nonce: true, + noModule: true + }; + + function DOMEval( code, node, doc ) { + doc = doc || document; + + var i, val, + script = doc.createElement( "script" ); + + script.text = code; + if ( node ) { + for ( i in preservedScriptAttributes ) { + + // Support: Firefox 64+, Edge 18+ + // Some browsers don't support the "nonce" property on scripts. + // On the other hand, just using `getAttribute` is not enough as + // the `nonce` attribute is reset to an empty string whenever it + // becomes browsing-context connected. + // See https://github.com/whatwg/html/issues/2369 + // See https://html.spec.whatwg.org/#nonce-attributes + // The `node.getAttribute` check was added for the sake of + // `jQuery.globalEval` so that it can fake a nonce-containing node + // via an object. + val = node[ i ] || node.getAttribute && node.getAttribute( i ); + if ( val ) { + script.setAttribute( i, val ); + } + } + } + doc.head.appendChild( script ).parentNode.removeChild( script ); + } + + +function toType( obj ) { + if ( obj == null ) { + return obj + ""; + } + + // Support: Android <=2.3 only (functionish RegExp) + return typeof obj === "object" || typeof obj === "function" ? + class2type[ toString.call( obj ) ] || "object" : + typeof obj; +} +/* global Symbol */ +// Defining this global in .eslintrc.json would create a danger of using the global +// unguarded in another place, it seems safer to define global only for this module + + + +var + version = "3.6.0", + + // Define a local copy of jQuery + jQuery = function( selector, context ) { + + // The jQuery object is actually just the init constructor 'enhanced' + // Need init if jQuery is called (just allow error to be thrown if not included) + return new jQuery.fn.init( selector, context ); + }; + +jQuery.fn = jQuery.prototype = { + + // The current version of jQuery being used + jquery: version, + + constructor: jQuery, + + // The default length of a jQuery object is 0 + length: 0, + + toArray: function() { + return slice.call( this ); + }, + + // Get the Nth element in the matched element set OR + // Get the whole matched element set as a clean array + get: function( num ) { + + // Return all the elements in a clean array + if ( num == null ) { + return slice.call( this ); + } + + // Return just the one element from the set + return num < 0 ? this[ num + this.length ] : this[ num ]; + }, + + // Take an array of elements and push it onto the stack + // (returning the new matched element set) + pushStack: function( elems ) { + + // Build a new jQuery matched element set + var ret = jQuery.merge( this.constructor(), elems ); + + // Add the old object onto the stack (as a reference) + ret.prevObject = this; + + // Return the newly-formed element set + return ret; + }, + + // Execute a callback for every element in the matched set. + each: function( callback ) { + return jQuery.each( this, callback ); + }, + + map: function( callback ) { + return this.pushStack( jQuery.map( this, function( elem, i ) { + return callback.call( elem, i, elem ); + } ) ); + }, + + slice: function() { + return this.pushStack( slice.apply( this, arguments ) ); + }, + + first: function() { + return this.eq( 0 ); + }, + + last: function() { + return this.eq( -1 ); + }, + + even: function() { + return this.pushStack( jQuery.grep( this, function( _elem, i ) { + return ( i + 1 ) % 2; + } ) ); + }, + + odd: function() { + return this.pushStack( jQuery.grep( this, function( _elem, i ) { + return i % 2; + } ) ); + }, + + eq: function( i ) { + var len = this.length, + j = +i + ( i < 0 ? len : 0 ); + return this.pushStack( j >= 0 && j < len ? [ this[ j ] ] : [] ); + }, + + end: function() { + return this.prevObject || this.constructor(); + }, + + // For internal use only. + // Behaves like an Array's method, not like a jQuery method. + push: push, + sort: arr.sort, + splice: arr.splice +}; + +jQuery.extend = jQuery.fn.extend = function() { + var options, name, src, copy, copyIsArray, clone, + target = arguments[ 0 ] || {}, + i = 1, + length = arguments.length, + deep = false; + + // Handle a deep copy situation + if ( typeof target === "boolean" ) { + deep = target; + + // Skip the boolean and the target + target = arguments[ i ] || {}; + i++; + } + + // Handle case when target is a string or something (possible in deep copy) + if ( typeof target !== "object" && !isFunction( target ) ) { + target = {}; + } + + // Extend jQuery itself if only one argument is passed + if ( i === length ) { + target = this; + i--; + } + + for ( ; i < length; i++ ) { + + // Only deal with non-null/undefined values + if ( ( options = arguments[ i ] ) != null ) { + + // Extend the base object + for ( name in options ) { + copy = options[ name ]; + + // Prevent Object.prototype pollution + // Prevent never-ending loop + if ( name === "__proto__" || target === copy ) { + continue; + } + + // Recurse if we're merging plain objects or arrays + if ( deep && copy && ( jQuery.isPlainObject( copy ) || + ( copyIsArray = Array.isArray( copy ) ) ) ) { + src = target[ name ]; + + // Ensure proper type for the source value + if ( copyIsArray && !Array.isArray( src ) ) { + clone = []; + } else if ( !copyIsArray && !jQuery.isPlainObject( src ) ) { + clone = {}; + } else { + clone = src; + } + copyIsArray = false; + + // Never move original objects, clone them + target[ name ] = jQuery.extend( deep, clone, copy ); + + // Don't bring in undefined values + } else if ( copy !== undefined ) { + target[ name ] = copy; + } + } + } + } + + // Return the modified object + return target; +}; + +jQuery.extend( { + + // Unique for each copy of jQuery on the page + expando: "jQuery" + ( version + Math.random() ).replace( /\D/g, "" ), + + // Assume jQuery is ready without the ready module + isReady: true, + + error: function( msg ) { + throw new Error( msg ); + }, + + noop: function() {}, + + isPlainObject: function( obj ) { + var proto, Ctor; + + // Detect obvious negatives + // Use toString instead of jQuery.type to catch host objects + if ( !obj || toString.call( obj ) !== "[object Object]" ) { + return false; + } + + proto = getProto( obj ); + + // Objects with no prototype (e.g., `Object.create( null )`) are plain + if ( !proto ) { + return true; + } + + // Objects with prototype are plain iff they were constructed by a global Object function + Ctor = hasOwn.call( proto, "constructor" ) && proto.constructor; + return typeof Ctor === "function" && fnToString.call( Ctor ) === ObjectFunctionString; + }, + + isEmptyObject: function( obj ) { + var name; + + for ( name in obj ) { + return false; + } + return true; + }, + + // Evaluates a script in a provided context; falls back to the global one + // if not specified. + globalEval: function( code, options, doc ) { + DOMEval( code, { nonce: options && options.nonce }, doc ); + }, + + each: function( obj, callback ) { + var length, i = 0; + + if ( isArrayLike( obj ) ) { + length = obj.length; + for ( ; i < length; i++ ) { + if ( callback.call( obj[ i ], i, obj[ i ] ) === false ) { + break; + } + } + } else { + for ( i in obj ) { + if ( callback.call( obj[ i ], i, obj[ i ] ) === false ) { + break; + } + } + } + + return obj; + }, + + // results is for internal usage only + makeArray: function( arr, results ) { + var ret = results || []; + + if ( arr != null ) { + if ( isArrayLike( Object( arr ) ) ) { + jQuery.merge( ret, + typeof arr === "string" ? + [ arr ] : arr + ); + } else { + push.call( ret, arr ); + } + } + + return ret; + }, + + inArray: function( elem, arr, i ) { + return arr == null ? -1 : indexOf.call( arr, elem, i ); + }, + + // Support: Android <=4.0 only, PhantomJS 1 only + // push.apply(_, arraylike) throws on ancient WebKit + merge: function( first, second ) { + var len = +second.length, + j = 0, + i = first.length; + + for ( ; j < len; j++ ) { + first[ i++ ] = second[ j ]; + } + + first.length = i; + + return first; + }, + + grep: function( elems, callback, invert ) { + var callbackInverse, + matches = [], + i = 0, + length = elems.length, + callbackExpect = !invert; + + // Go through the array, only saving the items + // that pass the validator function + for ( ; i < length; i++ ) { + callbackInverse = !callback( elems[ i ], i ); + if ( callbackInverse !== callbackExpect ) { + matches.push( elems[ i ] ); + } + } + + return matches; + }, + + // arg is for internal usage only + map: function( elems, callback, arg ) { + var length, value, + i = 0, + ret = []; + + // Go through the array, translating each of the items to their new values + if ( isArrayLike( elems ) ) { + length = elems.length; + for ( ; i < length; i++ ) { + value = callback( elems[ i ], i, arg ); + + if ( value != null ) { + ret.push( value ); + } + } + + // Go through every key on the object, + } else { + for ( i in elems ) { + value = callback( elems[ i ], i, arg ); + + if ( value != null ) { + ret.push( value ); + } + } + } + + // Flatten any nested arrays + return flat( ret ); + }, + + // A global GUID counter for objects + guid: 1, + + // jQuery.support is not used in Core but other projects attach their + // properties to it so it needs to exist. + support: support +} ); + +if ( typeof Symbol === "function" ) { + jQuery.fn[ Symbol.iterator ] = arr[ Symbol.iterator ]; +} + +// Populate the class2type map +jQuery.each( "Boolean Number String Function Array Date RegExp Object Error Symbol".split( " " ), + function( _i, name ) { + class2type[ "[object " + name + "]" ] = name.toLowerCase(); + } ); + +function isArrayLike( obj ) { + + // Support: real iOS 8.2 only (not reproducible in simulator) + // `in` check used to prevent JIT error (gh-2145) + // hasOwn isn't used here due to false negatives + // regarding Nodelist length in IE + var length = !!obj && "length" in obj && obj.length, + type = toType( obj ); + + if ( isFunction( obj ) || isWindow( obj ) ) { + return false; + } + + return type === "array" || length === 0 || + typeof length === "number" && length > 0 && ( length - 1 ) in obj; +} +var Sizzle = +/*! + * Sizzle CSS Selector Engine v2.3.6 + * https://sizzlejs.com/ + * + * Copyright JS Foundation and other contributors + * Released under the MIT license + * https://js.foundation/ + * + * Date: 2021-02-16 + */ +( function( window ) { +var i, + support, + Expr, + getText, + isXML, + tokenize, + compile, + select, + outermostContext, + sortInput, + hasDuplicate, + + // Local document vars + setDocument, + document, + docElem, + documentIsHTML, + rbuggyQSA, + rbuggyMatches, + matches, + contains, + + // Instance-specific data + expando = "sizzle" + 1 * new Date(), + preferredDoc = window.document, + dirruns = 0, + done = 0, + classCache = createCache(), + tokenCache = createCache(), + compilerCache = createCache(), + nonnativeSelectorCache = createCache(), + sortOrder = function( a, b ) { + if ( a === b ) { + hasDuplicate = true; + } + return 0; + }, + + // Instance methods + hasOwn = ( {} ).hasOwnProperty, + arr = [], + pop = arr.pop, + pushNative = arr.push, + push = arr.push, + slice = arr.slice, + + // Use a stripped-down indexOf as it's faster than native + // https://jsperf.com/thor-indexof-vs-for/5 + indexOf = function( list, elem ) { + var i = 0, + len = list.length; + for ( ; i < len; i++ ) { + if ( list[ i ] === elem ) { + return i; + } + } + return -1; + }, + + booleans = "checked|selected|async|autofocus|autoplay|controls|defer|disabled|hidden|" + + "ismap|loop|multiple|open|readonly|required|scoped", + + // Regular expressions + + // http://www.w3.org/TR/css3-selectors/#whitespace + whitespace = "[\\x20\\t\\r\\n\\f]", + + // https://www.w3.org/TR/css-syntax-3/#ident-token-diagram + identifier = "(?:\\\\[\\da-fA-F]{1,6}" + whitespace + + "?|\\\\[^\\r\\n\\f]|[\\w-]|[^\0-\\x7f])+", + + // Attribute selectors: http://www.w3.org/TR/selectors/#attribute-selectors + attributes = "\\[" + whitespace + "*(" + identifier + ")(?:" + whitespace + + + // Operator (capture 2) + "*([*^$|!~]?=)" + whitespace + + + // "Attribute values must be CSS identifiers [capture 5] + // or strings [capture 3 or capture 4]" + "*(?:'((?:\\\\.|[^\\\\'])*)'|\"((?:\\\\.|[^\\\\\"])*)\"|(" + identifier + "))|)" + + whitespace + "*\\]", + + pseudos = ":(" + identifier + ")(?:\\((" + + + // To reduce the number of selectors needing tokenize in the preFilter, prefer arguments: + // 1. quoted (capture 3; capture 4 or capture 5) + "('((?:\\\\.|[^\\\\'])*)'|\"((?:\\\\.|[^\\\\\"])*)\")|" + + + // 2. simple (capture 6) + "((?:\\\\.|[^\\\\()[\\]]|" + attributes + ")*)|" + + + // 3. anything else (capture 2) + ".*" + + ")\\)|)", + + // Leading and non-escaped trailing whitespace, capturing some non-whitespace characters preceding the latter + rwhitespace = new RegExp( whitespace + "+", "g" ), + rtrim = new RegExp( "^" + whitespace + "+|((?:^|[^\\\\])(?:\\\\.)*)" + + whitespace + "+$", "g" ), + + rcomma = new RegExp( "^" + whitespace + "*," + whitespace + "*" ), + rcombinators = new RegExp( "^" + whitespace + "*([>+~]|" + whitespace + ")" + whitespace + + "*" ), + rdescend = new RegExp( whitespace + "|>" ), + + rpseudo = new RegExp( pseudos ), + ridentifier = new RegExp( "^" + identifier + "$" ), + + matchExpr = { + "ID": new RegExp( "^#(" + identifier + ")" ), + "CLASS": new RegExp( "^\\.(" + identifier + ")" ), + "TAG": new RegExp( "^(" + identifier + "|[*])" ), + "ATTR": new RegExp( "^" + attributes ), + "PSEUDO": new RegExp( "^" + pseudos ), + "CHILD": new RegExp( "^:(only|first|last|nth|nth-last)-(child|of-type)(?:\\(" + + whitespace + "*(even|odd|(([+-]|)(\\d*)n|)" + whitespace + "*(?:([+-]|)" + + whitespace + "*(\\d+)|))" + whitespace + "*\\)|)", "i" ), + "bool": new RegExp( "^(?:" + booleans + ")$", "i" ), + + // For use in libraries implementing .is() + // We use this for POS matching in `select` + "needsContext": new RegExp( "^" + whitespace + + "*[>+~]|:(even|odd|eq|gt|lt|nth|first|last)(?:\\(" + whitespace + + "*((?:-\\d)?\\d*)" + whitespace + "*\\)|)(?=[^-]|$)", "i" ) + }, + + rhtml = /HTML$/i, + rinputs = /^(?:input|select|textarea|button)$/i, + rheader = /^h\d$/i, + + rnative = /^[^{]+\{\s*\[native \w/, + + // Easily-parseable/retrievable ID or TAG or CLASS selectors + rquickExpr = /^(?:#([\w-]+)|(\w+)|\.([\w-]+))$/, + + rsibling = /[+~]/, + + // CSS escapes + // http://www.w3.org/TR/CSS21/syndata.html#escaped-characters + runescape = new RegExp( "\\\\[\\da-fA-F]{1,6}" + whitespace + "?|\\\\([^\\r\\n\\f])", "g" ), + funescape = function( escape, nonHex ) { + var high = "0x" + escape.slice( 1 ) - 0x10000; + + return nonHex ? + + // Strip the backslash prefix from a non-hex escape sequence + nonHex : + + // Replace a hexadecimal escape sequence with the encoded Unicode code point + // Support: IE <=11+ + // For values outside the Basic Multilingual Plane (BMP), manually construct a + // surrogate pair + high < 0 ? + String.fromCharCode( high + 0x10000 ) : + String.fromCharCode( high >> 10 | 0xD800, high & 0x3FF | 0xDC00 ); + }, + + // CSS string/identifier serialization + // https://drafts.csswg.org/cssom/#common-serializing-idioms + rcssescape = /([\0-\x1f\x7f]|^-?\d)|^-$|[^\0-\x1f\x7f-\uFFFF\w-]/g, + fcssescape = function( ch, asCodePoint ) { + if ( asCodePoint ) { + + // U+0000 NULL becomes U+FFFD REPLACEMENT CHARACTER + if ( ch === "\0" ) { + return "\uFFFD"; + } + + // Control characters and (dependent upon position) numbers get escaped as code points + return ch.slice( 0, -1 ) + "\\" + + ch.charCodeAt( ch.length - 1 ).toString( 16 ) + " "; + } + + // Other potentially-special ASCII characters get backslash-escaped + return "\\" + ch; + }, + + // Used for iframes + // See setDocument() + // Removing the function wrapper causes a "Permission Denied" + // error in IE + unloadHandler = function() { + setDocument(); + }, + + inDisabledFieldset = addCombinator( + function( elem ) { + return elem.disabled === true && elem.nodeName.toLowerCase() === "fieldset"; + }, + { dir: "parentNode", next: "legend" } + ); + +// Optimize for push.apply( _, NodeList ) +try { + push.apply( + ( arr = slice.call( preferredDoc.childNodes ) ), + preferredDoc.childNodes + ); + + // Support: Android<4.0 + // Detect silently failing push.apply + // eslint-disable-next-line no-unused-expressions + arr[ preferredDoc.childNodes.length ].nodeType; +} catch ( e ) { + push = { apply: arr.length ? + + // Leverage slice if possible + function( target, els ) { + pushNative.apply( target, slice.call( els ) ); + } : + + // Support: IE<9 + // Otherwise append directly + function( target, els ) { + var j = target.length, + i = 0; + + // Can't trust NodeList.length + while ( ( target[ j++ ] = els[ i++ ] ) ) {} + target.length = j - 1; + } + }; +} + +function Sizzle( selector, context, results, seed ) { + var m, i, elem, nid, match, groups, newSelector, + newContext = context && context.ownerDocument, + + // nodeType defaults to 9, since context defaults to document + nodeType = context ? context.nodeType : 9; + + results = results || []; + + // Return early from calls with invalid selector or context + if ( typeof selector !== "string" || !selector || + nodeType !== 1 && nodeType !== 9 && nodeType !== 11 ) { + + return results; + } + + // Try to shortcut find operations (as opposed to filters) in HTML documents + if ( !seed ) { + setDocument( context ); + context = context || document; + + if ( documentIsHTML ) { + + // If the selector is sufficiently simple, try using a "get*By*" DOM method + // (excepting DocumentFragment context, where the methods don't exist) + if ( nodeType !== 11 && ( match = rquickExpr.exec( selector ) ) ) { + + // ID selector + if ( ( m = match[ 1 ] ) ) { + + // Document context + if ( nodeType === 9 ) { + if ( ( elem = context.getElementById( m ) ) ) { + + // Support: IE, Opera, Webkit + // TODO: identify versions + // getElementById can match elements by name instead of ID + if ( elem.id === m ) { + results.push( elem ); + return results; + } + } else { + return results; + } + + // Element context + } else { + + // Support: IE, Opera, Webkit + // TODO: identify versions + // getElementById can match elements by name instead of ID + if ( newContext && ( elem = newContext.getElementById( m ) ) && + contains( context, elem ) && + elem.id === m ) { + + results.push( elem ); + return results; + } + } + + // Type selector + } else if ( match[ 2 ] ) { + push.apply( results, context.getElementsByTagName( selector ) ); + return results; + + // Class selector + } else if ( ( m = match[ 3 ] ) && support.getElementsByClassName && + context.getElementsByClassName ) { + + push.apply( results, context.getElementsByClassName( m ) ); + return results; + } + } + + // Take advantage of querySelectorAll + if ( support.qsa && + !nonnativeSelectorCache[ selector + " " ] && + ( !rbuggyQSA || !rbuggyQSA.test( selector ) ) && + + // Support: IE 8 only + // Exclude object elements + ( nodeType !== 1 || context.nodeName.toLowerCase() !== "object" ) ) { + + newSelector = selector; + newContext = context; + + // qSA considers elements outside a scoping root when evaluating child or + // descendant combinators, which is not what we want. + // In such cases, we work around the behavior by prefixing every selector in the + // list with an ID selector referencing the scope context. + // The technique has to be used as well when a leading combinator is used + // as such selectors are not recognized by querySelectorAll. + // Thanks to Andrew Dupont for this technique. + if ( nodeType === 1 && + ( rdescend.test( selector ) || rcombinators.test( selector ) ) ) { + + // Expand context for sibling selectors + newContext = rsibling.test( selector ) && testContext( context.parentNode ) || + context; + + // We can use :scope instead of the ID hack if the browser + // supports it & if we're not changing the context. + if ( newContext !== context || !support.scope ) { + + // Capture the context ID, setting it first if necessary + if ( ( nid = context.getAttribute( "id" ) ) ) { + nid = nid.replace( rcssescape, fcssescape ); + } else { + context.setAttribute( "id", ( nid = expando ) ); + } + } + + // Prefix every selector in the list + groups = tokenize( selector ); + i = groups.length; + while ( i-- ) { + groups[ i ] = ( nid ? "#" + nid : ":scope" ) + " " + + toSelector( groups[ i ] ); + } + newSelector = groups.join( "," ); + } + + try { + push.apply( results, + newContext.querySelectorAll( newSelector ) + ); + return results; + } catch ( qsaError ) { + nonnativeSelectorCache( selector, true ); + } finally { + if ( nid === expando ) { + context.removeAttribute( "id" ); + } + } + } + } + } + + // All others + return select( selector.replace( rtrim, "$1" ), context, results, seed ); +} + +/** + * Create key-value caches of limited size + * @returns {function(string, object)} Returns the Object data after storing it on itself with + * property name the (space-suffixed) string and (if the cache is larger than Expr.cacheLength) + * deleting the oldest entry + */ +function createCache() { + var keys = []; + + function cache( key, value ) { + + // Use (key + " ") to avoid collision with native prototype properties (see Issue #157) + if ( keys.push( key + " " ) > Expr.cacheLength ) { + + // Only keep the most recent entries + delete cache[ keys.shift() ]; + } + return ( cache[ key + " " ] = value ); + } + return cache; +} + +/** + * Mark a function for special use by Sizzle + * @param {Function} fn The function to mark + */ +function markFunction( fn ) { + fn[ expando ] = true; + return fn; +} + +/** + * Support testing using an element + * @param {Function} fn Passed the created element and returns a boolean result + */ +function assert( fn ) { + var el = document.createElement( "fieldset" ); + + try { + return !!fn( el ); + } catch ( e ) { + return false; + } finally { + + // Remove from its parent by default + if ( el.parentNode ) { + el.parentNode.removeChild( el ); + } + + // release memory in IE + el = null; + } +} + +/** + * Adds the same handler for all of the specified attrs + * @param {String} attrs Pipe-separated list of attributes + * @param {Function} handler The method that will be applied + */ +function addHandle( attrs, handler ) { + var arr = attrs.split( "|" ), + i = arr.length; + + while ( i-- ) { + Expr.attrHandle[ arr[ i ] ] = handler; + } +} + +/** + * Checks document order of two siblings + * @param {Element} a + * @param {Element} b + * @returns {Number} Returns less than 0 if a precedes b, greater than 0 if a follows b + */ +function siblingCheck( a, b ) { + var cur = b && a, + diff = cur && a.nodeType === 1 && b.nodeType === 1 && + a.sourceIndex - b.sourceIndex; + + // Use IE sourceIndex if available on both nodes + if ( diff ) { + return diff; + } + + // Check if b follows a + if ( cur ) { + while ( ( cur = cur.nextSibling ) ) { + if ( cur === b ) { + return -1; + } + } + } + + return a ? 1 : -1; +} + +/** + * Returns a function to use in pseudos for input types + * @param {String} type + */ +function createInputPseudo( type ) { + return function( elem ) { + var name = elem.nodeName.toLowerCase(); + return name === "input" && elem.type === type; + }; +} + +/** + * Returns a function to use in pseudos for buttons + * @param {String} type + */ +function createButtonPseudo( type ) { + return function( elem ) { + var name = elem.nodeName.toLowerCase(); + return ( name === "input" || name === "button" ) && elem.type === type; + }; +} + +/** + * Returns a function to use in pseudos for :enabled/:disabled + * @param {Boolean} disabled true for :disabled; false for :enabled + */ +function createDisabledPseudo( disabled ) { + + // Known :disabled false positives: fieldset[disabled] > legend:nth-of-type(n+2) :can-disable + return function( elem ) { + + // Only certain elements can match :enabled or :disabled + // https://html.spec.whatwg.org/multipage/scripting.html#selector-enabled + // https://html.spec.whatwg.org/multipage/scripting.html#selector-disabled + if ( "form" in elem ) { + + // Check for inherited disabledness on relevant non-disabled elements: + // * listed form-associated elements in a disabled fieldset + // https://html.spec.whatwg.org/multipage/forms.html#category-listed + // https://html.spec.whatwg.org/multipage/forms.html#concept-fe-disabled + // * option elements in a disabled optgroup + // https://html.spec.whatwg.org/multipage/forms.html#concept-option-disabled + // All such elements have a "form" property. + if ( elem.parentNode && elem.disabled === false ) { + + // Option elements defer to a parent optgroup if present + if ( "label" in elem ) { + if ( "label" in elem.parentNode ) { + return elem.parentNode.disabled === disabled; + } else { + return elem.disabled === disabled; + } + } + + // Support: IE 6 - 11 + // Use the isDisabled shortcut property to check for disabled fieldset ancestors + return elem.isDisabled === disabled || + + // Where there is no isDisabled, check manually + /* jshint -W018 */ + elem.isDisabled !== !disabled && + inDisabledFieldset( elem ) === disabled; + } + + return elem.disabled === disabled; + + // Try to winnow out elements that can't be disabled before trusting the disabled property. + // Some victims get caught in our net (label, legend, menu, track), but it shouldn't + // even exist on them, let alone have a boolean value. + } else if ( "label" in elem ) { + return elem.disabled === disabled; + } + + // Remaining elements are neither :enabled nor :disabled + return false; + }; +} + +/** + * Returns a function to use in pseudos for positionals + * @param {Function} fn + */ +function createPositionalPseudo( fn ) { + return markFunction( function( argument ) { + argument = +argument; + return markFunction( function( seed, matches ) { + var j, + matchIndexes = fn( [], seed.length, argument ), + i = matchIndexes.length; + + // Match elements found at the specified indexes + while ( i-- ) { + if ( seed[ ( j = matchIndexes[ i ] ) ] ) { + seed[ j ] = !( matches[ j ] = seed[ j ] ); + } + } + } ); + } ); +} + +/** + * Checks a node for validity as a Sizzle context + * @param {Element|Object=} context + * @returns {Element|Object|Boolean} The input node if acceptable, otherwise a falsy value + */ +function testContext( context ) { + return context && typeof context.getElementsByTagName !== "undefined" && context; +} + +// Expose support vars for convenience +support = Sizzle.support = {}; + +/** + * Detects XML nodes + * @param {Element|Object} elem An element or a document + * @returns {Boolean} True iff elem is a non-HTML XML node + */ +isXML = Sizzle.isXML = function( elem ) { + var namespace = elem && elem.namespaceURI, + docElem = elem && ( elem.ownerDocument || elem ).documentElement; + + // Support: IE <=8 + // Assume HTML when documentElement doesn't yet exist, such as inside loading iframes + // https://bugs.jquery.com/ticket/4833 + return !rhtml.test( namespace || docElem && docElem.nodeName || "HTML" ); +}; + +/** + * Sets document-related variables once based on the current document + * @param {Element|Object} [doc] An element or document object to use to set the document + * @returns {Object} Returns the current document + */ +setDocument = Sizzle.setDocument = function( node ) { + var hasCompare, subWindow, + doc = node ? node.ownerDocument || node : preferredDoc; + + // Return early if doc is invalid or already selected + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( doc == document || doc.nodeType !== 9 || !doc.documentElement ) { + return document; + } + + // Update global variables + document = doc; + docElem = document.documentElement; + documentIsHTML = !isXML( document ); + + // Support: IE 9 - 11+, Edge 12 - 18+ + // Accessing iframe documents after unload throws "permission denied" errors (jQuery #13936) + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( preferredDoc != document && + ( subWindow = document.defaultView ) && subWindow.top !== subWindow ) { + + // Support: IE 11, Edge + if ( subWindow.addEventListener ) { + subWindow.addEventListener( "unload", unloadHandler, false ); + + // Support: IE 9 - 10 only + } else if ( subWindow.attachEvent ) { + subWindow.attachEvent( "onunload", unloadHandler ); + } + } + + // Support: IE 8 - 11+, Edge 12 - 18+, Chrome <=16 - 25 only, Firefox <=3.6 - 31 only, + // Safari 4 - 5 only, Opera <=11.6 - 12.x only + // IE/Edge & older browsers don't support the :scope pseudo-class. + // Support: Safari 6.0 only + // Safari 6.0 supports :scope but it's an alias of :root there. + support.scope = assert( function( el ) { + docElem.appendChild( el ).appendChild( document.createElement( "div" ) ); + return typeof el.querySelectorAll !== "undefined" && + !el.querySelectorAll( ":scope fieldset div" ).length; + } ); + + /* Attributes + ---------------------------------------------------------------------- */ + + // Support: IE<8 + // Verify that getAttribute really returns attributes and not properties + // (excepting IE8 booleans) + support.attributes = assert( function( el ) { + el.className = "i"; + return !el.getAttribute( "className" ); + } ); + + /* getElement(s)By* + ---------------------------------------------------------------------- */ + + // Check if getElementsByTagName("*") returns only elements + support.getElementsByTagName = assert( function( el ) { + el.appendChild( document.createComment( "" ) ); + return !el.getElementsByTagName( "*" ).length; + } ); + + // Support: IE<9 + support.getElementsByClassName = rnative.test( document.getElementsByClassName ); + + // Support: IE<10 + // Check if getElementById returns elements by name + // The broken getElementById methods don't pick up programmatically-set names, + // so use a roundabout getElementsByName test + support.getById = assert( function( el ) { + docElem.appendChild( el ).id = expando; + return !document.getElementsByName || !document.getElementsByName( expando ).length; + } ); + + // ID filter and find + if ( support.getById ) { + Expr.filter[ "ID" ] = function( id ) { + var attrId = id.replace( runescape, funescape ); + return function( elem ) { + return elem.getAttribute( "id" ) === attrId; + }; + }; + Expr.find[ "ID" ] = function( id, context ) { + if ( typeof context.getElementById !== "undefined" && documentIsHTML ) { + var elem = context.getElementById( id ); + return elem ? [ elem ] : []; + } + }; + } else { + Expr.filter[ "ID" ] = function( id ) { + var attrId = id.replace( runescape, funescape ); + return function( elem ) { + var node = typeof elem.getAttributeNode !== "undefined" && + elem.getAttributeNode( "id" ); + return node && node.value === attrId; + }; + }; + + // Support: IE 6 - 7 only + // getElementById is not reliable as a find shortcut + Expr.find[ "ID" ] = function( id, context ) { + if ( typeof context.getElementById !== "undefined" && documentIsHTML ) { + var node, i, elems, + elem = context.getElementById( id ); + + if ( elem ) { + + // Verify the id attribute + node = elem.getAttributeNode( "id" ); + if ( node && node.value === id ) { + return [ elem ]; + } + + // Fall back on getElementsByName + elems = context.getElementsByName( id ); + i = 0; + while ( ( elem = elems[ i++ ] ) ) { + node = elem.getAttributeNode( "id" ); + if ( node && node.value === id ) { + return [ elem ]; + } + } + } + + return []; + } + }; + } + + // Tag + Expr.find[ "TAG" ] = support.getElementsByTagName ? + function( tag, context ) { + if ( typeof context.getElementsByTagName !== "undefined" ) { + return context.getElementsByTagName( tag ); + + // DocumentFragment nodes don't have gEBTN + } else if ( support.qsa ) { + return context.querySelectorAll( tag ); + } + } : + + function( tag, context ) { + var elem, + tmp = [], + i = 0, + + // By happy coincidence, a (broken) gEBTN appears on DocumentFragment nodes too + results = context.getElementsByTagName( tag ); + + // Filter out possible comments + if ( tag === "*" ) { + while ( ( elem = results[ i++ ] ) ) { + if ( elem.nodeType === 1 ) { + tmp.push( elem ); + } + } + + return tmp; + } + return results; + }; + + // Class + Expr.find[ "CLASS" ] = support.getElementsByClassName && function( className, context ) { + if ( typeof context.getElementsByClassName !== "undefined" && documentIsHTML ) { + return context.getElementsByClassName( className ); + } + }; + + /* QSA/matchesSelector + ---------------------------------------------------------------------- */ + + // QSA and matchesSelector support + + // matchesSelector(:active) reports false when true (IE9/Opera 11.5) + rbuggyMatches = []; + + // qSa(:focus) reports false when true (Chrome 21) + // We allow this because of a bug in IE8/9 that throws an error + // whenever `document.activeElement` is accessed on an iframe + // So, we allow :focus to pass through QSA all the time to avoid the IE error + // See https://bugs.jquery.com/ticket/13378 + rbuggyQSA = []; + + if ( ( support.qsa = rnative.test( document.querySelectorAll ) ) ) { + + // Build QSA regex + // Regex strategy adopted from Diego Perini + assert( function( el ) { + + var input; + + // Select is set to empty string on purpose + // This is to test IE's treatment of not explicitly + // setting a boolean content attribute, + // since its presence should be enough + // https://bugs.jquery.com/ticket/12359 + docElem.appendChild( el ).innerHTML = "" + + ""; + + // Support: IE8, Opera 11-12.16 + // Nothing should be selected when empty strings follow ^= or $= or *= + // The test attribute must be unknown in Opera but "safe" for WinRT + // https://msdn.microsoft.com/en-us/library/ie/hh465388.aspx#attribute_section + if ( el.querySelectorAll( "[msallowcapture^='']" ).length ) { + rbuggyQSA.push( "[*^$]=" + whitespace + "*(?:''|\"\")" ); + } + + // Support: IE8 + // Boolean attributes and "value" are not treated correctly + if ( !el.querySelectorAll( "[selected]" ).length ) { + rbuggyQSA.push( "\\[" + whitespace + "*(?:value|" + booleans + ")" ); + } + + // Support: Chrome<29, Android<4.4, Safari<7.0+, iOS<7.0+, PhantomJS<1.9.8+ + if ( !el.querySelectorAll( "[id~=" + expando + "-]" ).length ) { + rbuggyQSA.push( "~=" ); + } + + // Support: IE 11+, Edge 15 - 18+ + // IE 11/Edge don't find elements on a `[name='']` query in some cases. + // Adding a temporary attribute to the document before the selection works + // around the issue. + // Interestingly, IE 10 & older don't seem to have the issue. + input = document.createElement( "input" ); + input.setAttribute( "name", "" ); + el.appendChild( input ); + if ( !el.querySelectorAll( "[name='']" ).length ) { + rbuggyQSA.push( "\\[" + whitespace + "*name" + whitespace + "*=" + + whitespace + "*(?:''|\"\")" ); + } + + // Webkit/Opera - :checked should return selected option elements + // http://www.w3.org/TR/2011/REC-css3-selectors-20110929/#checked + // IE8 throws error here and will not see later tests + if ( !el.querySelectorAll( ":checked" ).length ) { + rbuggyQSA.push( ":checked" ); + } + + // Support: Safari 8+, iOS 8+ + // https://bugs.webkit.org/show_bug.cgi?id=136851 + // In-page `selector#id sibling-combinator selector` fails + if ( !el.querySelectorAll( "a#" + expando + "+*" ).length ) { + rbuggyQSA.push( ".#.+[+~]" ); + } + + // Support: Firefox <=3.6 - 5 only + // Old Firefox doesn't throw on a badly-escaped identifier. + el.querySelectorAll( "\\\f" ); + rbuggyQSA.push( "[\\r\\n\\f]" ); + } ); + + assert( function( el ) { + el.innerHTML = "" + + ""; + + // Support: Windows 8 Native Apps + // The type and name attributes are restricted during .innerHTML assignment + var input = document.createElement( "input" ); + input.setAttribute( "type", "hidden" ); + el.appendChild( input ).setAttribute( "name", "D" ); + + // Support: IE8 + // Enforce case-sensitivity of name attribute + if ( el.querySelectorAll( "[name=d]" ).length ) { + rbuggyQSA.push( "name" + whitespace + "*[*^$|!~]?=" ); + } + + // FF 3.5 - :enabled/:disabled and hidden elements (hidden elements are still enabled) + // IE8 throws error here and will not see later tests + if ( el.querySelectorAll( ":enabled" ).length !== 2 ) { + rbuggyQSA.push( ":enabled", ":disabled" ); + } + + // Support: IE9-11+ + // IE's :disabled selector does not pick up the children of disabled fieldsets + docElem.appendChild( el ).disabled = true; + if ( el.querySelectorAll( ":disabled" ).length !== 2 ) { + rbuggyQSA.push( ":enabled", ":disabled" ); + } + + // Support: Opera 10 - 11 only + // Opera 10-11 does not throw on post-comma invalid pseudos + el.querySelectorAll( "*,:x" ); + rbuggyQSA.push( ",.*:" ); + } ); + } + + if ( ( support.matchesSelector = rnative.test( ( matches = docElem.matches || + docElem.webkitMatchesSelector || + docElem.mozMatchesSelector || + docElem.oMatchesSelector || + docElem.msMatchesSelector ) ) ) ) { + + assert( function( el ) { + + // Check to see if it's possible to do matchesSelector + // on a disconnected node (IE 9) + support.disconnectedMatch = matches.call( el, "*" ); + + // This should fail with an exception + // Gecko does not error, returns false instead + matches.call( el, "[s!='']:x" ); + rbuggyMatches.push( "!=", pseudos ); + } ); + } + + rbuggyQSA = rbuggyQSA.length && new RegExp( rbuggyQSA.join( "|" ) ); + rbuggyMatches = rbuggyMatches.length && new RegExp( rbuggyMatches.join( "|" ) ); + + /* Contains + ---------------------------------------------------------------------- */ + hasCompare = rnative.test( docElem.compareDocumentPosition ); + + // Element contains another + // Purposefully self-exclusive + // As in, an element does not contain itself + contains = hasCompare || rnative.test( docElem.contains ) ? + function( a, b ) { + var adown = a.nodeType === 9 ? a.documentElement : a, + bup = b && b.parentNode; + return a === bup || !!( bup && bup.nodeType === 1 && ( + adown.contains ? + adown.contains( bup ) : + a.compareDocumentPosition && a.compareDocumentPosition( bup ) & 16 + ) ); + } : + function( a, b ) { + if ( b ) { + while ( ( b = b.parentNode ) ) { + if ( b === a ) { + return true; + } + } + } + return false; + }; + + /* Sorting + ---------------------------------------------------------------------- */ + + // Document order sorting + sortOrder = hasCompare ? + function( a, b ) { + + // Flag for duplicate removal + if ( a === b ) { + hasDuplicate = true; + return 0; + } + + // Sort on method existence if only one input has compareDocumentPosition + var compare = !a.compareDocumentPosition - !b.compareDocumentPosition; + if ( compare ) { + return compare; + } + + // Calculate position if both inputs belong to the same document + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + compare = ( a.ownerDocument || a ) == ( b.ownerDocument || b ) ? + a.compareDocumentPosition( b ) : + + // Otherwise we know they are disconnected + 1; + + // Disconnected nodes + if ( compare & 1 || + ( !support.sortDetached && b.compareDocumentPosition( a ) === compare ) ) { + + // Choose the first element that is related to our preferred document + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( a == document || a.ownerDocument == preferredDoc && + contains( preferredDoc, a ) ) { + return -1; + } + + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( b == document || b.ownerDocument == preferredDoc && + contains( preferredDoc, b ) ) { + return 1; + } + + // Maintain original order + return sortInput ? + ( indexOf( sortInput, a ) - indexOf( sortInput, b ) ) : + 0; + } + + return compare & 4 ? -1 : 1; + } : + function( a, b ) { + + // Exit early if the nodes are identical + if ( a === b ) { + hasDuplicate = true; + return 0; + } + + var cur, + i = 0, + aup = a.parentNode, + bup = b.parentNode, + ap = [ a ], + bp = [ b ]; + + // Parentless nodes are either documents or disconnected + if ( !aup || !bup ) { + + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + /* eslint-disable eqeqeq */ + return a == document ? -1 : + b == document ? 1 : + /* eslint-enable eqeqeq */ + aup ? -1 : + bup ? 1 : + sortInput ? + ( indexOf( sortInput, a ) - indexOf( sortInput, b ) ) : + 0; + + // If the nodes are siblings, we can do a quick check + } else if ( aup === bup ) { + return siblingCheck( a, b ); + } + + // Otherwise we need full lists of their ancestors for comparison + cur = a; + while ( ( cur = cur.parentNode ) ) { + ap.unshift( cur ); + } + cur = b; + while ( ( cur = cur.parentNode ) ) { + bp.unshift( cur ); + } + + // Walk down the tree looking for a discrepancy + while ( ap[ i ] === bp[ i ] ) { + i++; + } + + return i ? + + // Do a sibling check if the nodes have a common ancestor + siblingCheck( ap[ i ], bp[ i ] ) : + + // Otherwise nodes in our document sort first + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + /* eslint-disable eqeqeq */ + ap[ i ] == preferredDoc ? -1 : + bp[ i ] == preferredDoc ? 1 : + /* eslint-enable eqeqeq */ + 0; + }; + + return document; +}; + +Sizzle.matches = function( expr, elements ) { + return Sizzle( expr, null, null, elements ); +}; + +Sizzle.matchesSelector = function( elem, expr ) { + setDocument( elem ); + + if ( support.matchesSelector && documentIsHTML && + !nonnativeSelectorCache[ expr + " " ] && + ( !rbuggyMatches || !rbuggyMatches.test( expr ) ) && + ( !rbuggyQSA || !rbuggyQSA.test( expr ) ) ) { + + try { + var ret = matches.call( elem, expr ); + + // IE 9's matchesSelector returns false on disconnected nodes + if ( ret || support.disconnectedMatch || + + // As well, disconnected nodes are said to be in a document + // fragment in IE 9 + elem.document && elem.document.nodeType !== 11 ) { + return ret; + } + } catch ( e ) { + nonnativeSelectorCache( expr, true ); + } + } + + return Sizzle( expr, document, null, [ elem ] ).length > 0; +}; + +Sizzle.contains = function( context, elem ) { + + // Set document vars if needed + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( ( context.ownerDocument || context ) != document ) { + setDocument( context ); + } + return contains( context, elem ); +}; + +Sizzle.attr = function( elem, name ) { + + // Set document vars if needed + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( ( elem.ownerDocument || elem ) != document ) { + setDocument( elem ); + } + + var fn = Expr.attrHandle[ name.toLowerCase() ], + + // Don't get fooled by Object.prototype properties (jQuery #13807) + val = fn && hasOwn.call( Expr.attrHandle, name.toLowerCase() ) ? + fn( elem, name, !documentIsHTML ) : + undefined; + + return val !== undefined ? + val : + support.attributes || !documentIsHTML ? + elem.getAttribute( name ) : + ( val = elem.getAttributeNode( name ) ) && val.specified ? + val.value : + null; +}; + +Sizzle.escape = function( sel ) { + return ( sel + "" ).replace( rcssescape, fcssescape ); +}; + +Sizzle.error = function( msg ) { + throw new Error( "Syntax error, unrecognized expression: " + msg ); +}; + +/** + * Document sorting and removing duplicates + * @param {ArrayLike} results + */ +Sizzle.uniqueSort = function( results ) { + var elem, + duplicates = [], + j = 0, + i = 0; + + // Unless we *know* we can detect duplicates, assume their presence + hasDuplicate = !support.detectDuplicates; + sortInput = !support.sortStable && results.slice( 0 ); + results.sort( sortOrder ); + + if ( hasDuplicate ) { + while ( ( elem = results[ i++ ] ) ) { + if ( elem === results[ i ] ) { + j = duplicates.push( i ); + } + } + while ( j-- ) { + results.splice( duplicates[ j ], 1 ); + } + } + + // Clear input after sorting to release objects + // See https://github.com/jquery/sizzle/pull/225 + sortInput = null; + + return results; +}; + +/** + * Utility function for retrieving the text value of an array of DOM nodes + * @param {Array|Element} elem + */ +getText = Sizzle.getText = function( elem ) { + var node, + ret = "", + i = 0, + nodeType = elem.nodeType; + + if ( !nodeType ) { + + // If no nodeType, this is expected to be an array + while ( ( node = elem[ i++ ] ) ) { + + // Do not traverse comment nodes + ret += getText( node ); + } + } else if ( nodeType === 1 || nodeType === 9 || nodeType === 11 ) { + + // Use textContent for elements + // innerText usage removed for consistency of new lines (jQuery #11153) + if ( typeof elem.textContent === "string" ) { + return elem.textContent; + } else { + + // Traverse its children + for ( elem = elem.firstChild; elem; elem = elem.nextSibling ) { + ret += getText( elem ); + } + } + } else if ( nodeType === 3 || nodeType === 4 ) { + return elem.nodeValue; + } + + // Do not include comment or processing instruction nodes + + return ret; +}; + +Expr = Sizzle.selectors = { + + // Can be adjusted by the user + cacheLength: 50, + + createPseudo: markFunction, + + match: matchExpr, + + attrHandle: {}, + + find: {}, + + relative: { + ">": { dir: "parentNode", first: true }, + " ": { dir: "parentNode" }, + "+": { dir: "previousSibling", first: true }, + "~": { dir: "previousSibling" } + }, + + preFilter: { + "ATTR": function( match ) { + match[ 1 ] = match[ 1 ].replace( runescape, funescape ); + + // Move the given value to match[3] whether quoted or unquoted + match[ 3 ] = ( match[ 3 ] || match[ 4 ] || + match[ 5 ] || "" ).replace( runescape, funescape ); + + if ( match[ 2 ] === "~=" ) { + match[ 3 ] = " " + match[ 3 ] + " "; + } + + return match.slice( 0, 4 ); + }, + + "CHILD": function( match ) { + + /* matches from matchExpr["CHILD"] + 1 type (only|nth|...) + 2 what (child|of-type) + 3 argument (even|odd|\d*|\d*n([+-]\d+)?|...) + 4 xn-component of xn+y argument ([+-]?\d*n|) + 5 sign of xn-component + 6 x of xn-component + 7 sign of y-component + 8 y of y-component + */ + match[ 1 ] = match[ 1 ].toLowerCase(); + + if ( match[ 1 ].slice( 0, 3 ) === "nth" ) { + + // nth-* requires argument + if ( !match[ 3 ] ) { + Sizzle.error( match[ 0 ] ); + } + + // numeric x and y parameters for Expr.filter.CHILD + // remember that false/true cast respectively to 0/1 + match[ 4 ] = +( match[ 4 ] ? + match[ 5 ] + ( match[ 6 ] || 1 ) : + 2 * ( match[ 3 ] === "even" || match[ 3 ] === "odd" ) ); + match[ 5 ] = +( ( match[ 7 ] + match[ 8 ] ) || match[ 3 ] === "odd" ); + + // other types prohibit arguments + } else if ( match[ 3 ] ) { + Sizzle.error( match[ 0 ] ); + } + + return match; + }, + + "PSEUDO": function( match ) { + var excess, + unquoted = !match[ 6 ] && match[ 2 ]; + + if ( matchExpr[ "CHILD" ].test( match[ 0 ] ) ) { + return null; + } + + // Accept quoted arguments as-is + if ( match[ 3 ] ) { + match[ 2 ] = match[ 4 ] || match[ 5 ] || ""; + + // Strip excess characters from unquoted arguments + } else if ( unquoted && rpseudo.test( unquoted ) && + + // Get excess from tokenize (recursively) + ( excess = tokenize( unquoted, true ) ) && + + // advance to the next closing parenthesis + ( excess = unquoted.indexOf( ")", unquoted.length - excess ) - unquoted.length ) ) { + + // excess is a negative index + match[ 0 ] = match[ 0 ].slice( 0, excess ); + match[ 2 ] = unquoted.slice( 0, excess ); + } + + // Return only captures needed by the pseudo filter method (type and argument) + return match.slice( 0, 3 ); + } + }, + + filter: { + + "TAG": function( nodeNameSelector ) { + var nodeName = nodeNameSelector.replace( runescape, funescape ).toLowerCase(); + return nodeNameSelector === "*" ? + function() { + return true; + } : + function( elem ) { + return elem.nodeName && elem.nodeName.toLowerCase() === nodeName; + }; + }, + + "CLASS": function( className ) { + var pattern = classCache[ className + " " ]; + + return pattern || + ( pattern = new RegExp( "(^|" + whitespace + + ")" + className + "(" + whitespace + "|$)" ) ) && classCache( + className, function( elem ) { + return pattern.test( + typeof elem.className === "string" && elem.className || + typeof elem.getAttribute !== "undefined" && + elem.getAttribute( "class" ) || + "" + ); + } ); + }, + + "ATTR": function( name, operator, check ) { + return function( elem ) { + var result = Sizzle.attr( elem, name ); + + if ( result == null ) { + return operator === "!="; + } + if ( !operator ) { + return true; + } + + result += ""; + + /* eslint-disable max-len */ + + return operator === "=" ? result === check : + operator === "!=" ? result !== check : + operator === "^=" ? check && result.indexOf( check ) === 0 : + operator === "*=" ? check && result.indexOf( check ) > -1 : + operator === "$=" ? check && result.slice( -check.length ) === check : + operator === "~=" ? ( " " + result.replace( rwhitespace, " " ) + " " ).indexOf( check ) > -1 : + operator === "|=" ? result === check || result.slice( 0, check.length + 1 ) === check + "-" : + false; + /* eslint-enable max-len */ + + }; + }, + + "CHILD": function( type, what, _argument, first, last ) { + var simple = type.slice( 0, 3 ) !== "nth", + forward = type.slice( -4 ) !== "last", + ofType = what === "of-type"; + + return first === 1 && last === 0 ? + + // Shortcut for :nth-*(n) + function( elem ) { + return !!elem.parentNode; + } : + + function( elem, _context, xml ) { + var cache, uniqueCache, outerCache, node, nodeIndex, start, + dir = simple !== forward ? "nextSibling" : "previousSibling", + parent = elem.parentNode, + name = ofType && elem.nodeName.toLowerCase(), + useCache = !xml && !ofType, + diff = false; + + if ( parent ) { + + // :(first|last|only)-(child|of-type) + if ( simple ) { + while ( dir ) { + node = elem; + while ( ( node = node[ dir ] ) ) { + if ( ofType ? + node.nodeName.toLowerCase() === name : + node.nodeType === 1 ) { + + return false; + } + } + + // Reverse direction for :only-* (if we haven't yet done so) + start = dir = type === "only" && !start && "nextSibling"; + } + return true; + } + + start = [ forward ? parent.firstChild : parent.lastChild ]; + + // non-xml :nth-child(...) stores cache data on `parent` + if ( forward && useCache ) { + + // Seek `elem` from a previously-cached index + + // ...in a gzip-friendly way + node = parent; + outerCache = node[ expando ] || ( node[ expando ] = {} ); + + // Support: IE <9 only + // Defend against cloned attroperties (jQuery gh-1709) + uniqueCache = outerCache[ node.uniqueID ] || + ( outerCache[ node.uniqueID ] = {} ); + + cache = uniqueCache[ type ] || []; + nodeIndex = cache[ 0 ] === dirruns && cache[ 1 ]; + diff = nodeIndex && cache[ 2 ]; + node = nodeIndex && parent.childNodes[ nodeIndex ]; + + while ( ( node = ++nodeIndex && node && node[ dir ] || + + // Fallback to seeking `elem` from the start + ( diff = nodeIndex = 0 ) || start.pop() ) ) { + + // When found, cache indexes on `parent` and break + if ( node.nodeType === 1 && ++diff && node === elem ) { + uniqueCache[ type ] = [ dirruns, nodeIndex, diff ]; + break; + } + } + + } else { + + // Use previously-cached element index if available + if ( useCache ) { + + // ...in a gzip-friendly way + node = elem; + outerCache = node[ expando ] || ( node[ expando ] = {} ); + + // Support: IE <9 only + // Defend against cloned attroperties (jQuery gh-1709) + uniqueCache = outerCache[ node.uniqueID ] || + ( outerCache[ node.uniqueID ] = {} ); + + cache = uniqueCache[ type ] || []; + nodeIndex = cache[ 0 ] === dirruns && cache[ 1 ]; + diff = nodeIndex; + } + + // xml :nth-child(...) + // or :nth-last-child(...) or :nth(-last)?-of-type(...) + if ( diff === false ) { + + // Use the same loop as above to seek `elem` from the start + while ( ( node = ++nodeIndex && node && node[ dir ] || + ( diff = nodeIndex = 0 ) || start.pop() ) ) { + + if ( ( ofType ? + node.nodeName.toLowerCase() === name : + node.nodeType === 1 ) && + ++diff ) { + + // Cache the index of each encountered element + if ( useCache ) { + outerCache = node[ expando ] || + ( node[ expando ] = {} ); + + // Support: IE <9 only + // Defend against cloned attroperties (jQuery gh-1709) + uniqueCache = outerCache[ node.uniqueID ] || + ( outerCache[ node.uniqueID ] = {} ); + + uniqueCache[ type ] = [ dirruns, diff ]; + } + + if ( node === elem ) { + break; + } + } + } + } + } + + // Incorporate the offset, then check against cycle size + diff -= last; + return diff === first || ( diff % first === 0 && diff / first >= 0 ); + } + }; + }, + + "PSEUDO": function( pseudo, argument ) { + + // pseudo-class names are case-insensitive + // http://www.w3.org/TR/selectors/#pseudo-classes + // Prioritize by case sensitivity in case custom pseudos are added with uppercase letters + // Remember that setFilters inherits from pseudos + var args, + fn = Expr.pseudos[ pseudo ] || Expr.setFilters[ pseudo.toLowerCase() ] || + Sizzle.error( "unsupported pseudo: " + pseudo ); + + // The user may use createPseudo to indicate that + // arguments are needed to create the filter function + // just as Sizzle does + if ( fn[ expando ] ) { + return fn( argument ); + } + + // But maintain support for old signatures + if ( fn.length > 1 ) { + args = [ pseudo, pseudo, "", argument ]; + return Expr.setFilters.hasOwnProperty( pseudo.toLowerCase() ) ? + markFunction( function( seed, matches ) { + var idx, + matched = fn( seed, argument ), + i = matched.length; + while ( i-- ) { + idx = indexOf( seed, matched[ i ] ); + seed[ idx ] = !( matches[ idx ] = matched[ i ] ); + } + } ) : + function( elem ) { + return fn( elem, 0, args ); + }; + } + + return fn; + } + }, + + pseudos: { + + // Potentially complex pseudos + "not": markFunction( function( selector ) { + + // Trim the selector passed to compile + // to avoid treating leading and trailing + // spaces as combinators + var input = [], + results = [], + matcher = compile( selector.replace( rtrim, "$1" ) ); + + return matcher[ expando ] ? + markFunction( function( seed, matches, _context, xml ) { + var elem, + unmatched = matcher( seed, null, xml, [] ), + i = seed.length; + + // Match elements unmatched by `matcher` + while ( i-- ) { + if ( ( elem = unmatched[ i ] ) ) { + seed[ i ] = !( matches[ i ] = elem ); + } + } + } ) : + function( elem, _context, xml ) { + input[ 0 ] = elem; + matcher( input, null, xml, results ); + + // Don't keep the element (issue #299) + input[ 0 ] = null; + return !results.pop(); + }; + } ), + + "has": markFunction( function( selector ) { + return function( elem ) { + return Sizzle( selector, elem ).length > 0; + }; + } ), + + "contains": markFunction( function( text ) { + text = text.replace( runescape, funescape ); + return function( elem ) { + return ( elem.textContent || getText( elem ) ).indexOf( text ) > -1; + }; + } ), + + // "Whether an element is represented by a :lang() selector + // is based solely on the element's language value + // being equal to the identifier C, + // or beginning with the identifier C immediately followed by "-". + // The matching of C against the element's language value is performed case-insensitively. + // The identifier C does not have to be a valid language name." + // http://www.w3.org/TR/selectors/#lang-pseudo + "lang": markFunction( function( lang ) { + + // lang value must be a valid identifier + if ( !ridentifier.test( lang || "" ) ) { + Sizzle.error( "unsupported lang: " + lang ); + } + lang = lang.replace( runescape, funescape ).toLowerCase(); + return function( elem ) { + var elemLang; + do { + if ( ( elemLang = documentIsHTML ? + elem.lang : + elem.getAttribute( "xml:lang" ) || elem.getAttribute( "lang" ) ) ) { + + elemLang = elemLang.toLowerCase(); + return elemLang === lang || elemLang.indexOf( lang + "-" ) === 0; + } + } while ( ( elem = elem.parentNode ) && elem.nodeType === 1 ); + return false; + }; + } ), + + // Miscellaneous + "target": function( elem ) { + var hash = window.location && window.location.hash; + return hash && hash.slice( 1 ) === elem.id; + }, + + "root": function( elem ) { + return elem === docElem; + }, + + "focus": function( elem ) { + return elem === document.activeElement && + ( !document.hasFocus || document.hasFocus() ) && + !!( elem.type || elem.href || ~elem.tabIndex ); + }, + + // Boolean properties + "enabled": createDisabledPseudo( false ), + "disabled": createDisabledPseudo( true ), + + "checked": function( elem ) { + + // In CSS3, :checked should return both checked and selected elements + // http://www.w3.org/TR/2011/REC-css3-selectors-20110929/#checked + var nodeName = elem.nodeName.toLowerCase(); + return ( nodeName === "input" && !!elem.checked ) || + ( nodeName === "option" && !!elem.selected ); + }, + + "selected": function( elem ) { + + // Accessing this property makes selected-by-default + // options in Safari work properly + if ( elem.parentNode ) { + // eslint-disable-next-line no-unused-expressions + elem.parentNode.selectedIndex; + } + + return elem.selected === true; + }, + + // Contents + "empty": function( elem ) { + + // http://www.w3.org/TR/selectors/#empty-pseudo + // :empty is negated by element (1) or content nodes (text: 3; cdata: 4; entity ref: 5), + // but not by others (comment: 8; processing instruction: 7; etc.) + // nodeType < 6 works because attributes (2) do not appear as children + for ( elem = elem.firstChild; elem; elem = elem.nextSibling ) { + if ( elem.nodeType < 6 ) { + return false; + } + } + return true; + }, + + "parent": function( elem ) { + return !Expr.pseudos[ "empty" ]( elem ); + }, + + // Element/input types + "header": function( elem ) { + return rheader.test( elem.nodeName ); + }, + + "input": function( elem ) { + return rinputs.test( elem.nodeName ); + }, + + "button": function( elem ) { + var name = elem.nodeName.toLowerCase(); + return name === "input" && elem.type === "button" || name === "button"; + }, + + "text": function( elem ) { + var attr; + return elem.nodeName.toLowerCase() === "input" && + elem.type === "text" && + + // Support: IE<8 + // New HTML5 attribute values (e.g., "search") appear with elem.type === "text" + ( ( attr = elem.getAttribute( "type" ) ) == null || + attr.toLowerCase() === "text" ); + }, + + // Position-in-collection + "first": createPositionalPseudo( function() { + return [ 0 ]; + } ), + + "last": createPositionalPseudo( function( _matchIndexes, length ) { + return [ length - 1 ]; + } ), + + "eq": createPositionalPseudo( function( _matchIndexes, length, argument ) { + return [ argument < 0 ? argument + length : argument ]; + } ), + + "even": createPositionalPseudo( function( matchIndexes, length ) { + var i = 0; + for ( ; i < length; i += 2 ) { + matchIndexes.push( i ); + } + return matchIndexes; + } ), + + "odd": createPositionalPseudo( function( matchIndexes, length ) { + var i = 1; + for ( ; i < length; i += 2 ) { + matchIndexes.push( i ); + } + return matchIndexes; + } ), + + "lt": createPositionalPseudo( function( matchIndexes, length, argument ) { + var i = argument < 0 ? + argument + length : + argument > length ? + length : + argument; + for ( ; --i >= 0; ) { + matchIndexes.push( i ); + } + return matchIndexes; + } ), + + "gt": createPositionalPseudo( function( matchIndexes, length, argument ) { + var i = argument < 0 ? argument + length : argument; + for ( ; ++i < length; ) { + matchIndexes.push( i ); + } + return matchIndexes; + } ) + } +}; + +Expr.pseudos[ "nth" ] = Expr.pseudos[ "eq" ]; + +// Add button/input type pseudos +for ( i in { radio: true, checkbox: true, file: true, password: true, image: true } ) { + Expr.pseudos[ i ] = createInputPseudo( i ); +} +for ( i in { submit: true, reset: true } ) { + Expr.pseudos[ i ] = createButtonPseudo( i ); +} + +// Easy API for creating new setFilters +function setFilters() {} +setFilters.prototype = Expr.filters = Expr.pseudos; +Expr.setFilters = new setFilters(); + +tokenize = Sizzle.tokenize = function( selector, parseOnly ) { + var matched, match, tokens, type, + soFar, groups, preFilters, + cached = tokenCache[ selector + " " ]; + + if ( cached ) { + return parseOnly ? 0 : cached.slice( 0 ); + } + + soFar = selector; + groups = []; + preFilters = Expr.preFilter; + + while ( soFar ) { + + // Comma and first run + if ( !matched || ( match = rcomma.exec( soFar ) ) ) { + if ( match ) { + + // Don't consume trailing commas as valid + soFar = soFar.slice( match[ 0 ].length ) || soFar; + } + groups.push( ( tokens = [] ) ); + } + + matched = false; + + // Combinators + if ( ( match = rcombinators.exec( soFar ) ) ) { + matched = match.shift(); + tokens.push( { + value: matched, + + // Cast descendant combinators to space + type: match[ 0 ].replace( rtrim, " " ) + } ); + soFar = soFar.slice( matched.length ); + } + + // Filters + for ( type in Expr.filter ) { + if ( ( match = matchExpr[ type ].exec( soFar ) ) && ( !preFilters[ type ] || + ( match = preFilters[ type ]( match ) ) ) ) { + matched = match.shift(); + tokens.push( { + value: matched, + type: type, + matches: match + } ); + soFar = soFar.slice( matched.length ); + } + } + + if ( !matched ) { + break; + } + } + + // Return the length of the invalid excess + // if we're just parsing + // Otherwise, throw an error or return tokens + return parseOnly ? + soFar.length : + soFar ? + Sizzle.error( selector ) : + + // Cache the tokens + tokenCache( selector, groups ).slice( 0 ); +}; + +function toSelector( tokens ) { + var i = 0, + len = tokens.length, + selector = ""; + for ( ; i < len; i++ ) { + selector += tokens[ i ].value; + } + return selector; +} + +function addCombinator( matcher, combinator, base ) { + var dir = combinator.dir, + skip = combinator.next, + key = skip || dir, + checkNonElements = base && key === "parentNode", + doneName = done++; + + return combinator.first ? + + // Check against closest ancestor/preceding element + function( elem, context, xml ) { + while ( ( elem = elem[ dir ] ) ) { + if ( elem.nodeType === 1 || checkNonElements ) { + return matcher( elem, context, xml ); + } + } + return false; + } : + + // Check against all ancestor/preceding elements + function( elem, context, xml ) { + var oldCache, uniqueCache, outerCache, + newCache = [ dirruns, doneName ]; + + // We can't set arbitrary data on XML nodes, so they don't benefit from combinator caching + if ( xml ) { + while ( ( elem = elem[ dir ] ) ) { + if ( elem.nodeType === 1 || checkNonElements ) { + if ( matcher( elem, context, xml ) ) { + return true; + } + } + } + } else { + while ( ( elem = elem[ dir ] ) ) { + if ( elem.nodeType === 1 || checkNonElements ) { + outerCache = elem[ expando ] || ( elem[ expando ] = {} ); + + // Support: IE <9 only + // Defend against cloned attroperties (jQuery gh-1709) + uniqueCache = outerCache[ elem.uniqueID ] || + ( outerCache[ elem.uniqueID ] = {} ); + + if ( skip && skip === elem.nodeName.toLowerCase() ) { + elem = elem[ dir ] || elem; + } else if ( ( oldCache = uniqueCache[ key ] ) && + oldCache[ 0 ] === dirruns && oldCache[ 1 ] === doneName ) { + + // Assign to newCache so results back-propagate to previous elements + return ( newCache[ 2 ] = oldCache[ 2 ] ); + } else { + + // Reuse newcache so results back-propagate to previous elements + uniqueCache[ key ] = newCache; + + // A match means we're done; a fail means we have to keep checking + if ( ( newCache[ 2 ] = matcher( elem, context, xml ) ) ) { + return true; + } + } + } + } + } + return false; + }; +} + +function elementMatcher( matchers ) { + return matchers.length > 1 ? + function( elem, context, xml ) { + var i = matchers.length; + while ( i-- ) { + if ( !matchers[ i ]( elem, context, xml ) ) { + return false; + } + } + return true; + } : + matchers[ 0 ]; +} + +function multipleContexts( selector, contexts, results ) { + var i = 0, + len = contexts.length; + for ( ; i < len; i++ ) { + Sizzle( selector, contexts[ i ], results ); + } + return results; +} + +function condense( unmatched, map, filter, context, xml ) { + var elem, + newUnmatched = [], + i = 0, + len = unmatched.length, + mapped = map != null; + + for ( ; i < len; i++ ) { + if ( ( elem = unmatched[ i ] ) ) { + if ( !filter || filter( elem, context, xml ) ) { + newUnmatched.push( elem ); + if ( mapped ) { + map.push( i ); + } + } + } + } + + return newUnmatched; +} + +function setMatcher( preFilter, selector, matcher, postFilter, postFinder, postSelector ) { + if ( postFilter && !postFilter[ expando ] ) { + postFilter = setMatcher( postFilter ); + } + if ( postFinder && !postFinder[ expando ] ) { + postFinder = setMatcher( postFinder, postSelector ); + } + return markFunction( function( seed, results, context, xml ) { + var temp, i, elem, + preMap = [], + postMap = [], + preexisting = results.length, + + // Get initial elements from seed or context + elems = seed || multipleContexts( + selector || "*", + context.nodeType ? [ context ] : context, + [] + ), + + // Prefilter to get matcher input, preserving a map for seed-results synchronization + matcherIn = preFilter && ( seed || !selector ) ? + condense( elems, preMap, preFilter, context, xml ) : + elems, + + matcherOut = matcher ? + + // If we have a postFinder, or filtered seed, or non-seed postFilter or preexisting results, + postFinder || ( seed ? preFilter : preexisting || postFilter ) ? + + // ...intermediate processing is necessary + [] : + + // ...otherwise use results directly + results : + matcherIn; + + // Find primary matches + if ( matcher ) { + matcher( matcherIn, matcherOut, context, xml ); + } + + // Apply postFilter + if ( postFilter ) { + temp = condense( matcherOut, postMap ); + postFilter( temp, [], context, xml ); + + // Un-match failing elements by moving them back to matcherIn + i = temp.length; + while ( i-- ) { + if ( ( elem = temp[ i ] ) ) { + matcherOut[ postMap[ i ] ] = !( matcherIn[ postMap[ i ] ] = elem ); + } + } + } + + if ( seed ) { + if ( postFinder || preFilter ) { + if ( postFinder ) { + + // Get the final matcherOut by condensing this intermediate into postFinder contexts + temp = []; + i = matcherOut.length; + while ( i-- ) { + if ( ( elem = matcherOut[ i ] ) ) { + + // Restore matcherIn since elem is not yet a final match + temp.push( ( matcherIn[ i ] = elem ) ); + } + } + postFinder( null, ( matcherOut = [] ), temp, xml ); + } + + // Move matched elements from seed to results to keep them synchronized + i = matcherOut.length; + while ( i-- ) { + if ( ( elem = matcherOut[ i ] ) && + ( temp = postFinder ? indexOf( seed, elem ) : preMap[ i ] ) > -1 ) { + + seed[ temp ] = !( results[ temp ] = elem ); + } + } + } + + // Add elements to results, through postFinder if defined + } else { + matcherOut = condense( + matcherOut === results ? + matcherOut.splice( preexisting, matcherOut.length ) : + matcherOut + ); + if ( postFinder ) { + postFinder( null, results, matcherOut, xml ); + } else { + push.apply( results, matcherOut ); + } + } + } ); +} + +function matcherFromTokens( tokens ) { + var checkContext, matcher, j, + len = tokens.length, + leadingRelative = Expr.relative[ tokens[ 0 ].type ], + implicitRelative = leadingRelative || Expr.relative[ " " ], + i = leadingRelative ? 1 : 0, + + // The foundational matcher ensures that elements are reachable from top-level context(s) + matchContext = addCombinator( function( elem ) { + return elem === checkContext; + }, implicitRelative, true ), + matchAnyContext = addCombinator( function( elem ) { + return indexOf( checkContext, elem ) > -1; + }, implicitRelative, true ), + matchers = [ function( elem, context, xml ) { + var ret = ( !leadingRelative && ( xml || context !== outermostContext ) ) || ( + ( checkContext = context ).nodeType ? + matchContext( elem, context, xml ) : + matchAnyContext( elem, context, xml ) ); + + // Avoid hanging onto element (issue #299) + checkContext = null; + return ret; + } ]; + + for ( ; i < len; i++ ) { + if ( ( matcher = Expr.relative[ tokens[ i ].type ] ) ) { + matchers = [ addCombinator( elementMatcher( matchers ), matcher ) ]; + } else { + matcher = Expr.filter[ tokens[ i ].type ].apply( null, tokens[ i ].matches ); + + // Return special upon seeing a positional matcher + if ( matcher[ expando ] ) { + + // Find the next relative operator (if any) for proper handling + j = ++i; + for ( ; j < len; j++ ) { + if ( Expr.relative[ tokens[ j ].type ] ) { + break; + } + } + return setMatcher( + i > 1 && elementMatcher( matchers ), + i > 1 && toSelector( + + // If the preceding token was a descendant combinator, insert an implicit any-element `*` + tokens + .slice( 0, i - 1 ) + .concat( { value: tokens[ i - 2 ].type === " " ? "*" : "" } ) + ).replace( rtrim, "$1" ), + matcher, + i < j && matcherFromTokens( tokens.slice( i, j ) ), + j < len && matcherFromTokens( ( tokens = tokens.slice( j ) ) ), + j < len && toSelector( tokens ) + ); + } + matchers.push( matcher ); + } + } + + return elementMatcher( matchers ); +} + +function matcherFromGroupMatchers( elementMatchers, setMatchers ) { + var bySet = setMatchers.length > 0, + byElement = elementMatchers.length > 0, + superMatcher = function( seed, context, xml, results, outermost ) { + var elem, j, matcher, + matchedCount = 0, + i = "0", + unmatched = seed && [], + setMatched = [], + contextBackup = outermostContext, + + // We must always have either seed elements or outermost context + elems = seed || byElement && Expr.find[ "TAG" ]( "*", outermost ), + + // Use integer dirruns iff this is the outermost matcher + dirrunsUnique = ( dirruns += contextBackup == null ? 1 : Math.random() || 0.1 ), + len = elems.length; + + if ( outermost ) { + + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + outermostContext = context == document || context || outermost; + } + + // Add elements passing elementMatchers directly to results + // Support: IE<9, Safari + // Tolerate NodeList properties (IE: "length"; Safari: ) matching elements by id + for ( ; i !== len && ( elem = elems[ i ] ) != null; i++ ) { + if ( byElement && elem ) { + j = 0; + + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( !context && elem.ownerDocument != document ) { + setDocument( elem ); + xml = !documentIsHTML; + } + while ( ( matcher = elementMatchers[ j++ ] ) ) { + if ( matcher( elem, context || document, xml ) ) { + results.push( elem ); + break; + } + } + if ( outermost ) { + dirruns = dirrunsUnique; + } + } + + // Track unmatched elements for set filters + if ( bySet ) { + + // They will have gone through all possible matchers + if ( ( elem = !matcher && elem ) ) { + matchedCount--; + } + + // Lengthen the array for every element, matched or not + if ( seed ) { + unmatched.push( elem ); + } + } + } + + // `i` is now the count of elements visited above, and adding it to `matchedCount` + // makes the latter nonnegative. + matchedCount += i; + + // Apply set filters to unmatched elements + // NOTE: This can be skipped if there are no unmatched elements (i.e., `matchedCount` + // equals `i`), unless we didn't visit _any_ elements in the above loop because we have + // no element matchers and no seed. + // Incrementing an initially-string "0" `i` allows `i` to remain a string only in that + // case, which will result in a "00" `matchedCount` that differs from `i` but is also + // numerically zero. + if ( bySet && i !== matchedCount ) { + j = 0; + while ( ( matcher = setMatchers[ j++ ] ) ) { + matcher( unmatched, setMatched, context, xml ); + } + + if ( seed ) { + + // Reintegrate element matches to eliminate the need for sorting + if ( matchedCount > 0 ) { + while ( i-- ) { + if ( !( unmatched[ i ] || setMatched[ i ] ) ) { + setMatched[ i ] = pop.call( results ); + } + } + } + + // Discard index placeholder values to get only actual matches + setMatched = condense( setMatched ); + } + + // Add matches to results + push.apply( results, setMatched ); + + // Seedless set matches succeeding multiple successful matchers stipulate sorting + if ( outermost && !seed && setMatched.length > 0 && + ( matchedCount + setMatchers.length ) > 1 ) { + + Sizzle.uniqueSort( results ); + } + } + + // Override manipulation of globals by nested matchers + if ( outermost ) { + dirruns = dirrunsUnique; + outermostContext = contextBackup; + } + + return unmatched; + }; + + return bySet ? + markFunction( superMatcher ) : + superMatcher; +} + +compile = Sizzle.compile = function( selector, match /* Internal Use Only */ ) { + var i, + setMatchers = [], + elementMatchers = [], + cached = compilerCache[ selector + " " ]; + + if ( !cached ) { + + // Generate a function of recursive functions that can be used to check each element + if ( !match ) { + match = tokenize( selector ); + } + i = match.length; + while ( i-- ) { + cached = matcherFromTokens( match[ i ] ); + if ( cached[ expando ] ) { + setMatchers.push( cached ); + } else { + elementMatchers.push( cached ); + } + } + + // Cache the compiled function + cached = compilerCache( + selector, + matcherFromGroupMatchers( elementMatchers, setMatchers ) + ); + + // Save selector and tokenization + cached.selector = selector; + } + return cached; +}; + +/** + * A low-level selection function that works with Sizzle's compiled + * selector functions + * @param {String|Function} selector A selector or a pre-compiled + * selector function built with Sizzle.compile + * @param {Element} context + * @param {Array} [results] + * @param {Array} [seed] A set of elements to match against + */ +select = Sizzle.select = function( selector, context, results, seed ) { + var i, tokens, token, type, find, + compiled = typeof selector === "function" && selector, + match = !seed && tokenize( ( selector = compiled.selector || selector ) ); + + results = results || []; + + // Try to minimize operations if there is only one selector in the list and no seed + // (the latter of which guarantees us context) + if ( match.length === 1 ) { + + // Reduce context if the leading compound selector is an ID + tokens = match[ 0 ] = match[ 0 ].slice( 0 ); + if ( tokens.length > 2 && ( token = tokens[ 0 ] ).type === "ID" && + context.nodeType === 9 && documentIsHTML && Expr.relative[ tokens[ 1 ].type ] ) { + + context = ( Expr.find[ "ID" ]( token.matches[ 0 ] + .replace( runescape, funescape ), context ) || [] )[ 0 ]; + if ( !context ) { + return results; + + // Precompiled matchers will still verify ancestry, so step up a level + } else if ( compiled ) { + context = context.parentNode; + } + + selector = selector.slice( tokens.shift().value.length ); + } + + // Fetch a seed set for right-to-left matching + i = matchExpr[ "needsContext" ].test( selector ) ? 0 : tokens.length; + while ( i-- ) { + token = tokens[ i ]; + + // Abort if we hit a combinator + if ( Expr.relative[ ( type = token.type ) ] ) { + break; + } + if ( ( find = Expr.find[ type ] ) ) { + + // Search, expanding context for leading sibling combinators + if ( ( seed = find( + token.matches[ 0 ].replace( runescape, funescape ), + rsibling.test( tokens[ 0 ].type ) && testContext( context.parentNode ) || + context + ) ) ) { + + // If seed is empty or no tokens remain, we can return early + tokens.splice( i, 1 ); + selector = seed.length && toSelector( tokens ); + if ( !selector ) { + push.apply( results, seed ); + return results; + } + + break; + } + } + } + } + + // Compile and execute a filtering function if one is not provided + // Provide `match` to avoid retokenization if we modified the selector above + ( compiled || compile( selector, match ) )( + seed, + context, + !documentIsHTML, + results, + !context || rsibling.test( selector ) && testContext( context.parentNode ) || context + ); + return results; +}; + +// One-time assignments + +// Sort stability +support.sortStable = expando.split( "" ).sort( sortOrder ).join( "" ) === expando; + +// Support: Chrome 14-35+ +// Always assume duplicates if they aren't passed to the comparison function +support.detectDuplicates = !!hasDuplicate; + +// Initialize against the default document +setDocument(); + +// Support: Webkit<537.32 - Safari 6.0.3/Chrome 25 (fixed in Chrome 27) +// Detached nodes confoundingly follow *each other* +support.sortDetached = assert( function( el ) { + + // Should return 1, but returns 4 (following) + return el.compareDocumentPosition( document.createElement( "fieldset" ) ) & 1; +} ); + +// Support: IE<8 +// Prevent attribute/property "interpolation" +// https://msdn.microsoft.com/en-us/library/ms536429%28VS.85%29.aspx +if ( !assert( function( el ) { + el.innerHTML = ""; + return el.firstChild.getAttribute( "href" ) === "#"; +} ) ) { + addHandle( "type|href|height|width", function( elem, name, isXML ) { + if ( !isXML ) { + return elem.getAttribute( name, name.toLowerCase() === "type" ? 1 : 2 ); + } + } ); +} + +// Support: IE<9 +// Use defaultValue in place of getAttribute("value") +if ( !support.attributes || !assert( function( el ) { + el.innerHTML = ""; + el.firstChild.setAttribute( "value", "" ); + return el.firstChild.getAttribute( "value" ) === ""; +} ) ) { + addHandle( "value", function( elem, _name, isXML ) { + if ( !isXML && elem.nodeName.toLowerCase() === "input" ) { + return elem.defaultValue; + } + } ); +} + +// Support: IE<9 +// Use getAttributeNode to fetch booleans when getAttribute lies +if ( !assert( function( el ) { + return el.getAttribute( "disabled" ) == null; +} ) ) { + addHandle( booleans, function( elem, name, isXML ) { + var val; + if ( !isXML ) { + return elem[ name ] === true ? name.toLowerCase() : + ( val = elem.getAttributeNode( name ) ) && val.specified ? + val.value : + null; + } + } ); +} + +return Sizzle; + +} )( window ); + + + +jQuery.find = Sizzle; +jQuery.expr = Sizzle.selectors; + +// Deprecated +jQuery.expr[ ":" ] = jQuery.expr.pseudos; +jQuery.uniqueSort = jQuery.unique = Sizzle.uniqueSort; +jQuery.text = Sizzle.getText; +jQuery.isXMLDoc = Sizzle.isXML; +jQuery.contains = Sizzle.contains; +jQuery.escapeSelector = Sizzle.escape; + + + + +var dir = function( elem, dir, until ) { + var matched = [], + truncate = until !== undefined; + + while ( ( elem = elem[ dir ] ) && elem.nodeType !== 9 ) { + if ( elem.nodeType === 1 ) { + if ( truncate && jQuery( elem ).is( until ) ) { + break; + } + matched.push( elem ); + } + } + return matched; +}; + + +var siblings = function( n, elem ) { + var matched = []; + + for ( ; n; n = n.nextSibling ) { + if ( n.nodeType === 1 && n !== elem ) { + matched.push( n ); + } + } + + return matched; +}; + + +var rneedsContext = jQuery.expr.match.needsContext; + + + +function nodeName( elem, name ) { + + return elem.nodeName && elem.nodeName.toLowerCase() === name.toLowerCase(); + +} +var rsingleTag = ( /^<([a-z][^\/\0>:\x20\t\r\n\f]*)[\x20\t\r\n\f]*\/?>(?:<\/\1>|)$/i ); + + + +// Implement the identical functionality for filter and not +function winnow( elements, qualifier, not ) { + if ( isFunction( qualifier ) ) { + return jQuery.grep( elements, function( elem, i ) { + return !!qualifier.call( elem, i, elem ) !== not; + } ); + } + + // Single element + if ( qualifier.nodeType ) { + return jQuery.grep( elements, function( elem ) { + return ( elem === qualifier ) !== not; + } ); + } + + // Arraylike of elements (jQuery, arguments, Array) + if ( typeof qualifier !== "string" ) { + return jQuery.grep( elements, function( elem ) { + return ( indexOf.call( qualifier, elem ) > -1 ) !== not; + } ); + } + + // Filtered directly for both simple and complex selectors + return jQuery.filter( qualifier, elements, not ); +} + +jQuery.filter = function( expr, elems, not ) { + var elem = elems[ 0 ]; + + if ( not ) { + expr = ":not(" + expr + ")"; + } + + if ( elems.length === 1 && elem.nodeType === 1 ) { + return jQuery.find.matchesSelector( elem, expr ) ? [ elem ] : []; + } + + return jQuery.find.matches( expr, jQuery.grep( elems, function( elem ) { + return elem.nodeType === 1; + } ) ); +}; + +jQuery.fn.extend( { + find: function( selector ) { + var i, ret, + len = this.length, + self = this; + + if ( typeof selector !== "string" ) { + return this.pushStack( jQuery( selector ).filter( function() { + for ( i = 0; i < len; i++ ) { + if ( jQuery.contains( self[ i ], this ) ) { + return true; + } + } + } ) ); + } + + ret = this.pushStack( [] ); + + for ( i = 0; i < len; i++ ) { + jQuery.find( selector, self[ i ], ret ); + } + + return len > 1 ? jQuery.uniqueSort( ret ) : ret; + }, + filter: function( selector ) { + return this.pushStack( winnow( this, selector || [], false ) ); + }, + not: function( selector ) { + return this.pushStack( winnow( this, selector || [], true ) ); + }, + is: function( selector ) { + return !!winnow( + this, + + // If this is a positional/relative selector, check membership in the returned set + // so $("p:first").is("p:last") won't return true for a doc with two "p". + typeof selector === "string" && rneedsContext.test( selector ) ? + jQuery( selector ) : + selector || [], + false + ).length; + } +} ); + + +// Initialize a jQuery object + + +// A central reference to the root jQuery(document) +var rootjQuery, + + // A simple way to check for HTML strings + // Prioritize #id over to avoid XSS via location.hash (#9521) + // Strict HTML recognition (#11290: must start with <) + // Shortcut simple #id case for speed + rquickExpr = /^(?:\s*(<[\w\W]+>)[^>]*|#([\w-]+))$/, + + init = jQuery.fn.init = function( selector, context, root ) { + var match, elem; + + // HANDLE: $(""), $(null), $(undefined), $(false) + if ( !selector ) { + return this; + } + + // Method init() accepts an alternate rootjQuery + // so migrate can support jQuery.sub (gh-2101) + root = root || rootjQuery; + + // Handle HTML strings + if ( typeof selector === "string" ) { + if ( selector[ 0 ] === "<" && + selector[ selector.length - 1 ] === ">" && + selector.length >= 3 ) { + + // Assume that strings that start and end with <> are HTML and skip the regex check + match = [ null, selector, null ]; + + } else { + match = rquickExpr.exec( selector ); + } + + // Match html or make sure no context is specified for #id + if ( match && ( match[ 1 ] || !context ) ) { + + // HANDLE: $(html) -> $(array) + if ( match[ 1 ] ) { + context = context instanceof jQuery ? context[ 0 ] : context; + + // Option to run scripts is true for back-compat + // Intentionally let the error be thrown if parseHTML is not present + jQuery.merge( this, jQuery.parseHTML( + match[ 1 ], + context && context.nodeType ? context.ownerDocument || context : document, + true + ) ); + + // HANDLE: $(html, props) + if ( rsingleTag.test( match[ 1 ] ) && jQuery.isPlainObject( context ) ) { + for ( match in context ) { + + // Properties of context are called as methods if possible + if ( isFunction( this[ match ] ) ) { + this[ match ]( context[ match ] ); + + // ...and otherwise set as attributes + } else { + this.attr( match, context[ match ] ); + } + } + } + + return this; + + // HANDLE: $(#id) + } else { + elem = document.getElementById( match[ 2 ] ); + + if ( elem ) { + + // Inject the element directly into the jQuery object + this[ 0 ] = elem; + this.length = 1; + } + return this; + } + + // HANDLE: $(expr, $(...)) + } else if ( !context || context.jquery ) { + return ( context || root ).find( selector ); + + // HANDLE: $(expr, context) + // (which is just equivalent to: $(context).find(expr) + } else { + return this.constructor( context ).find( selector ); + } + + // HANDLE: $(DOMElement) + } else if ( selector.nodeType ) { + this[ 0 ] = selector; + this.length = 1; + return this; + + // HANDLE: $(function) + // Shortcut for document ready + } else if ( isFunction( selector ) ) { + return root.ready !== undefined ? + root.ready( selector ) : + + // Execute immediately if ready is not present + selector( jQuery ); + } + + return jQuery.makeArray( selector, this ); + }; + +// Give the init function the jQuery prototype for later instantiation +init.prototype = jQuery.fn; + +// Initialize central reference +rootjQuery = jQuery( document ); + + +var rparentsprev = /^(?:parents|prev(?:Until|All))/, + + // Methods guaranteed to produce a unique set when starting from a unique set + guaranteedUnique = { + children: true, + contents: true, + next: true, + prev: true + }; + +jQuery.fn.extend( { + has: function( target ) { + var targets = jQuery( target, this ), + l = targets.length; + + return this.filter( function() { + var i = 0; + for ( ; i < l; i++ ) { + if ( jQuery.contains( this, targets[ i ] ) ) { + return true; + } + } + } ); + }, + + closest: function( selectors, context ) { + var cur, + i = 0, + l = this.length, + matched = [], + targets = typeof selectors !== "string" && jQuery( selectors ); + + // Positional selectors never match, since there's no _selection_ context + if ( !rneedsContext.test( selectors ) ) { + for ( ; i < l; i++ ) { + for ( cur = this[ i ]; cur && cur !== context; cur = cur.parentNode ) { + + // Always skip document fragments + if ( cur.nodeType < 11 && ( targets ? + targets.index( cur ) > -1 : + + // Don't pass non-elements to Sizzle + cur.nodeType === 1 && + jQuery.find.matchesSelector( cur, selectors ) ) ) { + + matched.push( cur ); + break; + } + } + } + } + + return this.pushStack( matched.length > 1 ? jQuery.uniqueSort( matched ) : matched ); + }, + + // Determine the position of an element within the set + index: function( elem ) { + + // No argument, return index in parent + if ( !elem ) { + return ( this[ 0 ] && this[ 0 ].parentNode ) ? this.first().prevAll().length : -1; + } + + // Index in selector + if ( typeof elem === "string" ) { + return indexOf.call( jQuery( elem ), this[ 0 ] ); + } + + // Locate the position of the desired element + return indexOf.call( this, + + // If it receives a jQuery object, the first element is used + elem.jquery ? elem[ 0 ] : elem + ); + }, + + add: function( selector, context ) { + return this.pushStack( + jQuery.uniqueSort( + jQuery.merge( this.get(), jQuery( selector, context ) ) + ) + ); + }, + + addBack: function( selector ) { + return this.add( selector == null ? + this.prevObject : this.prevObject.filter( selector ) + ); + } +} ); + +function sibling( cur, dir ) { + while ( ( cur = cur[ dir ] ) && cur.nodeType !== 1 ) {} + return cur; +} + +jQuery.each( { + parent: function( elem ) { + var parent = elem.parentNode; + return parent && parent.nodeType !== 11 ? parent : null; + }, + parents: function( elem ) { + return dir( elem, "parentNode" ); + }, + parentsUntil: function( elem, _i, until ) { + return dir( elem, "parentNode", until ); + }, + next: function( elem ) { + return sibling( elem, "nextSibling" ); + }, + prev: function( elem ) { + return sibling( elem, "previousSibling" ); + }, + nextAll: function( elem ) { + return dir( elem, "nextSibling" ); + }, + prevAll: function( elem ) { + return dir( elem, "previousSibling" ); + }, + nextUntil: function( elem, _i, until ) { + return dir( elem, "nextSibling", until ); + }, + prevUntil: function( elem, _i, until ) { + return dir( elem, "previousSibling", until ); + }, + siblings: function( elem ) { + return siblings( ( elem.parentNode || {} ).firstChild, elem ); + }, + children: function( elem ) { + return siblings( elem.firstChild ); + }, + contents: function( elem ) { + if ( elem.contentDocument != null && + + // Support: IE 11+ + // elements with no `data` attribute has an object + // `contentDocument` with a `null` prototype. + getProto( elem.contentDocument ) ) { + + return elem.contentDocument; + } + + // Support: IE 9 - 11 only, iOS 7 only, Android Browser <=4.3 only + // Treat the template element as a regular one in browsers that + // don't support it. + if ( nodeName( elem, "template" ) ) { + elem = elem.content || elem; + } + + return jQuery.merge( [], elem.childNodes ); + } +}, function( name, fn ) { + jQuery.fn[ name ] = function( until, selector ) { + var matched = jQuery.map( this, fn, until ); + + if ( name.slice( -5 ) !== "Until" ) { + selector = until; + } + + if ( selector && typeof selector === "string" ) { + matched = jQuery.filter( selector, matched ); + } + + if ( this.length > 1 ) { + + // Remove duplicates + if ( !guaranteedUnique[ name ] ) { + jQuery.uniqueSort( matched ); + } + + // Reverse order for parents* and prev-derivatives + if ( rparentsprev.test( name ) ) { + matched.reverse(); + } + } + + return this.pushStack( matched ); + }; +} ); +var rnothtmlwhite = ( /[^\x20\t\r\n\f]+/g ); + + + +// Convert String-formatted options into Object-formatted ones +function createOptions( options ) { + var object = {}; + jQuery.each( options.match( rnothtmlwhite ) || [], function( _, flag ) { + object[ flag ] = true; + } ); + return object; +} + +/* + * Create a callback list using the following parameters: + * + * options: an optional list of space-separated options that will change how + * the callback list behaves or a more traditional option object + * + * By default a callback list will act like an event callback list and can be + * "fired" multiple times. + * + * Possible options: + * + * once: will ensure the callback list can only be fired once (like a Deferred) + * + * memory: will keep track of previous values and will call any callback added + * after the list has been fired right away with the latest "memorized" + * values (like a Deferred) + * + * unique: will ensure a callback can only be added once (no duplicate in the list) + * + * stopOnFalse: interrupt callings when a callback returns false + * + */ +jQuery.Callbacks = function( options ) { + + // Convert options from String-formatted to Object-formatted if needed + // (we check in cache first) + options = typeof options === "string" ? + createOptions( options ) : + jQuery.extend( {}, options ); + + var // Flag to know if list is currently firing + firing, + + // Last fire value for non-forgettable lists + memory, + + // Flag to know if list was already fired + fired, + + // Flag to prevent firing + locked, + + // Actual callback list + list = [], + + // Queue of execution data for repeatable lists + queue = [], + + // Index of currently firing callback (modified by add/remove as needed) + firingIndex = -1, + + // Fire callbacks + fire = function() { + + // Enforce single-firing + locked = locked || options.once; + + // Execute callbacks for all pending executions, + // respecting firingIndex overrides and runtime changes + fired = firing = true; + for ( ; queue.length; firingIndex = -1 ) { + memory = queue.shift(); + while ( ++firingIndex < list.length ) { + + // Run callback and check for early termination + if ( list[ firingIndex ].apply( memory[ 0 ], memory[ 1 ] ) === false && + options.stopOnFalse ) { + + // Jump to end and forget the data so .add doesn't re-fire + firingIndex = list.length; + memory = false; + } + } + } + + // Forget the data if we're done with it + if ( !options.memory ) { + memory = false; + } + + firing = false; + + // Clean up if we're done firing for good + if ( locked ) { + + // Keep an empty list if we have data for future add calls + if ( memory ) { + list = []; + + // Otherwise, this object is spent + } else { + list = ""; + } + } + }, + + // Actual Callbacks object + self = { + + // Add a callback or a collection of callbacks to the list + add: function() { + if ( list ) { + + // If we have memory from a past run, we should fire after adding + if ( memory && !firing ) { + firingIndex = list.length - 1; + queue.push( memory ); + } + + ( function add( args ) { + jQuery.each( args, function( _, arg ) { + if ( isFunction( arg ) ) { + if ( !options.unique || !self.has( arg ) ) { + list.push( arg ); + } + } else if ( arg && arg.length && toType( arg ) !== "string" ) { + + // Inspect recursively + add( arg ); + } + } ); + } )( arguments ); + + if ( memory && !firing ) { + fire(); + } + } + return this; + }, + + // Remove a callback from the list + remove: function() { + jQuery.each( arguments, function( _, arg ) { + var index; + while ( ( index = jQuery.inArray( arg, list, index ) ) > -1 ) { + list.splice( index, 1 ); + + // Handle firing indexes + if ( index <= firingIndex ) { + firingIndex--; + } + } + } ); + return this; + }, + + // Check if a given callback is in the list. + // If no argument is given, return whether or not list has callbacks attached. + has: function( fn ) { + return fn ? + jQuery.inArray( fn, list ) > -1 : + list.length > 0; + }, + + // Remove all callbacks from the list + empty: function() { + if ( list ) { + list = []; + } + return this; + }, + + // Disable .fire and .add + // Abort any current/pending executions + // Clear all callbacks and values + disable: function() { + locked = queue = []; + list = memory = ""; + return this; + }, + disabled: function() { + return !list; + }, + + // Disable .fire + // Also disable .add unless we have memory (since it would have no effect) + // Abort any pending executions + lock: function() { + locked = queue = []; + if ( !memory && !firing ) { + list = memory = ""; + } + return this; + }, + locked: function() { + return !!locked; + }, + + // Call all callbacks with the given context and arguments + fireWith: function( context, args ) { + if ( !locked ) { + args = args || []; + args = [ context, args.slice ? args.slice() : args ]; + queue.push( args ); + if ( !firing ) { + fire(); + } + } + return this; + }, + + // Call all the callbacks with the given arguments + fire: function() { + self.fireWith( this, arguments ); + return this; + }, + + // To know if the callbacks have already been called at least once + fired: function() { + return !!fired; + } + }; + + return self; +}; + + +function Identity( v ) { + return v; +} +function Thrower( ex ) { + throw ex; +} + +function adoptValue( value, resolve, reject, noValue ) { + var method; + + try { + + // Check for promise aspect first to privilege synchronous behavior + if ( value && isFunction( ( method = value.promise ) ) ) { + method.call( value ).done( resolve ).fail( reject ); + + // Other thenables + } else if ( value && isFunction( ( method = value.then ) ) ) { + method.call( value, resolve, reject ); + + // Other non-thenables + } else { + + // Control `resolve` arguments by letting Array#slice cast boolean `noValue` to integer: + // * false: [ value ].slice( 0 ) => resolve( value ) + // * true: [ value ].slice( 1 ) => resolve() + resolve.apply( undefined, [ value ].slice( noValue ) ); + } + + // For Promises/A+, convert exceptions into rejections + // Since jQuery.when doesn't unwrap thenables, we can skip the extra checks appearing in + // Deferred#then to conditionally suppress rejection. + } catch ( value ) { + + // Support: Android 4.0 only + // Strict mode functions invoked without .call/.apply get global-object context + reject.apply( undefined, [ value ] ); + } +} + +jQuery.extend( { + + Deferred: function( func ) { + var tuples = [ + + // action, add listener, callbacks, + // ... .then handlers, argument index, [final state] + [ "notify", "progress", jQuery.Callbacks( "memory" ), + jQuery.Callbacks( "memory" ), 2 ], + [ "resolve", "done", jQuery.Callbacks( "once memory" ), + jQuery.Callbacks( "once memory" ), 0, "resolved" ], + [ "reject", "fail", jQuery.Callbacks( "once memory" ), + jQuery.Callbacks( "once memory" ), 1, "rejected" ] + ], + state = "pending", + promise = { + state: function() { + return state; + }, + always: function() { + deferred.done( arguments ).fail( arguments ); + return this; + }, + "catch": function( fn ) { + return promise.then( null, fn ); + }, + + // Keep pipe for back-compat + pipe: function( /* fnDone, fnFail, fnProgress */ ) { + var fns = arguments; + + return jQuery.Deferred( function( newDefer ) { + jQuery.each( tuples, function( _i, tuple ) { + + // Map tuples (progress, done, fail) to arguments (done, fail, progress) + var fn = isFunction( fns[ tuple[ 4 ] ] ) && fns[ tuple[ 4 ] ]; + + // deferred.progress(function() { bind to newDefer or newDefer.notify }) + // deferred.done(function() { bind to newDefer or newDefer.resolve }) + // deferred.fail(function() { bind to newDefer or newDefer.reject }) + deferred[ tuple[ 1 ] ]( function() { + var returned = fn && fn.apply( this, arguments ); + if ( returned && isFunction( returned.promise ) ) { + returned.promise() + .progress( newDefer.notify ) + .done( newDefer.resolve ) + .fail( newDefer.reject ); + } else { + newDefer[ tuple[ 0 ] + "With" ]( + this, + fn ? [ returned ] : arguments + ); + } + } ); + } ); + fns = null; + } ).promise(); + }, + then: function( onFulfilled, onRejected, onProgress ) { + var maxDepth = 0; + function resolve( depth, deferred, handler, special ) { + return function() { + var that = this, + args = arguments, + mightThrow = function() { + var returned, then; + + // Support: Promises/A+ section 2.3.3.3.3 + // https://promisesaplus.com/#point-59 + // Ignore double-resolution attempts + if ( depth < maxDepth ) { + return; + } + + returned = handler.apply( that, args ); + + // Support: Promises/A+ section 2.3.1 + // https://promisesaplus.com/#point-48 + if ( returned === deferred.promise() ) { + throw new TypeError( "Thenable self-resolution" ); + } + + // Support: Promises/A+ sections 2.3.3.1, 3.5 + // https://promisesaplus.com/#point-54 + // https://promisesaplus.com/#point-75 + // Retrieve `then` only once + then = returned && + + // Support: Promises/A+ section 2.3.4 + // https://promisesaplus.com/#point-64 + // Only check objects and functions for thenability + ( typeof returned === "object" || + typeof returned === "function" ) && + returned.then; + + // Handle a returned thenable + if ( isFunction( then ) ) { + + // Special processors (notify) just wait for resolution + if ( special ) { + then.call( + returned, + resolve( maxDepth, deferred, Identity, special ), + resolve( maxDepth, deferred, Thrower, special ) + ); + + // Normal processors (resolve) also hook into progress + } else { + + // ...and disregard older resolution values + maxDepth++; + + then.call( + returned, + resolve( maxDepth, deferred, Identity, special ), + resolve( maxDepth, deferred, Thrower, special ), + resolve( maxDepth, deferred, Identity, + deferred.notifyWith ) + ); + } + + // Handle all other returned values + } else { + + // Only substitute handlers pass on context + // and multiple values (non-spec behavior) + if ( handler !== Identity ) { + that = undefined; + args = [ returned ]; + } + + // Process the value(s) + // Default process is resolve + ( special || deferred.resolveWith )( that, args ); + } + }, + + // Only normal processors (resolve) catch and reject exceptions + process = special ? + mightThrow : + function() { + try { + mightThrow(); + } catch ( e ) { + + if ( jQuery.Deferred.exceptionHook ) { + jQuery.Deferred.exceptionHook( e, + process.stackTrace ); + } + + // Support: Promises/A+ section 2.3.3.3.4.1 + // https://promisesaplus.com/#point-61 + // Ignore post-resolution exceptions + if ( depth + 1 >= maxDepth ) { + + // Only substitute handlers pass on context + // and multiple values (non-spec behavior) + if ( handler !== Thrower ) { + that = undefined; + args = [ e ]; + } + + deferred.rejectWith( that, args ); + } + } + }; + + // Support: Promises/A+ section 2.3.3.3.1 + // https://promisesaplus.com/#point-57 + // Re-resolve promises immediately to dodge false rejection from + // subsequent errors + if ( depth ) { + process(); + } else { + + // Call an optional hook to record the stack, in case of exception + // since it's otherwise lost when execution goes async + if ( jQuery.Deferred.getStackHook ) { + process.stackTrace = jQuery.Deferred.getStackHook(); + } + window.setTimeout( process ); + } + }; + } + + return jQuery.Deferred( function( newDefer ) { + + // progress_handlers.add( ... ) + tuples[ 0 ][ 3 ].add( + resolve( + 0, + newDefer, + isFunction( onProgress ) ? + onProgress : + Identity, + newDefer.notifyWith + ) + ); + + // fulfilled_handlers.add( ... ) + tuples[ 1 ][ 3 ].add( + resolve( + 0, + newDefer, + isFunction( onFulfilled ) ? + onFulfilled : + Identity + ) + ); + + // rejected_handlers.add( ... ) + tuples[ 2 ][ 3 ].add( + resolve( + 0, + newDefer, + isFunction( onRejected ) ? + onRejected : + Thrower + ) + ); + } ).promise(); + }, + + // Get a promise for this deferred + // If obj is provided, the promise aspect is added to the object + promise: function( obj ) { + return obj != null ? jQuery.extend( obj, promise ) : promise; + } + }, + deferred = {}; + + // Add list-specific methods + jQuery.each( tuples, function( i, tuple ) { + var list = tuple[ 2 ], + stateString = tuple[ 5 ]; + + // promise.progress = list.add + // promise.done = list.add + // promise.fail = list.add + promise[ tuple[ 1 ] ] = list.add; + + // Handle state + if ( stateString ) { + list.add( + function() { + + // state = "resolved" (i.e., fulfilled) + // state = "rejected" + state = stateString; + }, + + // rejected_callbacks.disable + // fulfilled_callbacks.disable + tuples[ 3 - i ][ 2 ].disable, + + // rejected_handlers.disable + // fulfilled_handlers.disable + tuples[ 3 - i ][ 3 ].disable, + + // progress_callbacks.lock + tuples[ 0 ][ 2 ].lock, + + // progress_handlers.lock + tuples[ 0 ][ 3 ].lock + ); + } + + // progress_handlers.fire + // fulfilled_handlers.fire + // rejected_handlers.fire + list.add( tuple[ 3 ].fire ); + + // deferred.notify = function() { deferred.notifyWith(...) } + // deferred.resolve = function() { deferred.resolveWith(...) } + // deferred.reject = function() { deferred.rejectWith(...) } + deferred[ tuple[ 0 ] ] = function() { + deferred[ tuple[ 0 ] + "With" ]( this === deferred ? undefined : this, arguments ); + return this; + }; + + // deferred.notifyWith = list.fireWith + // deferred.resolveWith = list.fireWith + // deferred.rejectWith = list.fireWith + deferred[ tuple[ 0 ] + "With" ] = list.fireWith; + } ); + + // Make the deferred a promise + promise.promise( deferred ); + + // Call given func if any + if ( func ) { + func.call( deferred, deferred ); + } + + // All done! + return deferred; + }, + + // Deferred helper + when: function( singleValue ) { + var + + // count of uncompleted subordinates + remaining = arguments.length, + + // count of unprocessed arguments + i = remaining, + + // subordinate fulfillment data + resolveContexts = Array( i ), + resolveValues = slice.call( arguments ), + + // the primary Deferred + primary = jQuery.Deferred(), + + // subordinate callback factory + updateFunc = function( i ) { + return function( value ) { + resolveContexts[ i ] = this; + resolveValues[ i ] = arguments.length > 1 ? slice.call( arguments ) : value; + if ( !( --remaining ) ) { + primary.resolveWith( resolveContexts, resolveValues ); + } + }; + }; + + // Single- and empty arguments are adopted like Promise.resolve + if ( remaining <= 1 ) { + adoptValue( singleValue, primary.done( updateFunc( i ) ).resolve, primary.reject, + !remaining ); + + // Use .then() to unwrap secondary thenables (cf. gh-3000) + if ( primary.state() === "pending" || + isFunction( resolveValues[ i ] && resolveValues[ i ].then ) ) { + + return primary.then(); + } + } + + // Multiple arguments are aggregated like Promise.all array elements + while ( i-- ) { + adoptValue( resolveValues[ i ], updateFunc( i ), primary.reject ); + } + + return primary.promise(); + } +} ); + + +// These usually indicate a programmer mistake during development, +// warn about them ASAP rather than swallowing them by default. +var rerrorNames = /^(Eval|Internal|Range|Reference|Syntax|Type|URI)Error$/; + +jQuery.Deferred.exceptionHook = function( error, stack ) { + + // Support: IE 8 - 9 only + // Console exists when dev tools are open, which can happen at any time + if ( window.console && window.console.warn && error && rerrorNames.test( error.name ) ) { + window.console.warn( "jQuery.Deferred exception: " + error.message, error.stack, stack ); + } +}; + + + + +jQuery.readyException = function( error ) { + window.setTimeout( function() { + throw error; + } ); +}; + + + + +// The deferred used on DOM ready +var readyList = jQuery.Deferred(); + +jQuery.fn.ready = function( fn ) { + + readyList + .then( fn ) + + // Wrap jQuery.readyException in a function so that the lookup + // happens at the time of error handling instead of callback + // registration. + .catch( function( error ) { + jQuery.readyException( error ); + } ); + + return this; +}; + +jQuery.extend( { + + // Is the DOM ready to be used? Set to true once it occurs. + isReady: false, + + // A counter to track how many items to wait for before + // the ready event fires. See #6781 + readyWait: 1, + + // Handle when the DOM is ready + ready: function( wait ) { + + // Abort if there are pending holds or we're already ready + if ( wait === true ? --jQuery.readyWait : jQuery.isReady ) { + return; + } + + // Remember that the DOM is ready + jQuery.isReady = true; + + // If a normal DOM Ready event fired, decrement, and wait if need be + if ( wait !== true && --jQuery.readyWait > 0 ) { + return; + } + + // If there are functions bound, to execute + readyList.resolveWith( document, [ jQuery ] ); + } +} ); + +jQuery.ready.then = readyList.then; + +// The ready event handler and self cleanup method +function completed() { + document.removeEventListener( "DOMContentLoaded", completed ); + window.removeEventListener( "load", completed ); + jQuery.ready(); +} + +// Catch cases where $(document).ready() is called +// after the browser event has already occurred. +// Support: IE <=9 - 10 only +// Older IE sometimes signals "interactive" too soon +if ( document.readyState === "complete" || + ( document.readyState !== "loading" && !document.documentElement.doScroll ) ) { + + // Handle it asynchronously to allow scripts the opportunity to delay ready + window.setTimeout( jQuery.ready ); + +} else { + + // Use the handy event callback + document.addEventListener( "DOMContentLoaded", completed ); + + // A fallback to window.onload, that will always work + window.addEventListener( "load", completed ); +} + + + + +// Multifunctional method to get and set values of a collection +// The value/s can optionally be executed if it's a function +var access = function( elems, fn, key, value, chainable, emptyGet, raw ) { + var i = 0, + len = elems.length, + bulk = key == null; + + // Sets many values + if ( toType( key ) === "object" ) { + chainable = true; + for ( i in key ) { + access( elems, fn, i, key[ i ], true, emptyGet, raw ); + } + + // Sets one value + } else if ( value !== undefined ) { + chainable = true; + + if ( !isFunction( value ) ) { + raw = true; + } + + if ( bulk ) { + + // Bulk operations run against the entire set + if ( raw ) { + fn.call( elems, value ); + fn = null; + + // ...except when executing function values + } else { + bulk = fn; + fn = function( elem, _key, value ) { + return bulk.call( jQuery( elem ), value ); + }; + } + } + + if ( fn ) { + for ( ; i < len; i++ ) { + fn( + elems[ i ], key, raw ? + value : + value.call( elems[ i ], i, fn( elems[ i ], key ) ) + ); + } + } + } + + if ( chainable ) { + return elems; + } + + // Gets + if ( bulk ) { + return fn.call( elems ); + } + + return len ? fn( elems[ 0 ], key ) : emptyGet; +}; + + +// Matches dashed string for camelizing +var rmsPrefix = /^-ms-/, + rdashAlpha = /-([a-z])/g; + +// Used by camelCase as callback to replace() +function fcamelCase( _all, letter ) { + return letter.toUpperCase(); +} + +// Convert dashed to camelCase; used by the css and data modules +// Support: IE <=9 - 11, Edge 12 - 15 +// Microsoft forgot to hump their vendor prefix (#9572) +function camelCase( string ) { + return string.replace( rmsPrefix, "ms-" ).replace( rdashAlpha, fcamelCase ); +} +var acceptData = function( owner ) { + + // Accepts only: + // - Node + // - Node.ELEMENT_NODE + // - Node.DOCUMENT_NODE + // - Object + // - Any + return owner.nodeType === 1 || owner.nodeType === 9 || !( +owner.nodeType ); +}; + + + + +function Data() { + this.expando = jQuery.expando + Data.uid++; +} + +Data.uid = 1; + +Data.prototype = { + + cache: function( owner ) { + + // Check if the owner object already has a cache + var value = owner[ this.expando ]; + + // If not, create one + if ( !value ) { + value = {}; + + // We can accept data for non-element nodes in modern browsers, + // but we should not, see #8335. + // Always return an empty object. + if ( acceptData( owner ) ) { + + // If it is a node unlikely to be stringify-ed or looped over + // use plain assignment + if ( owner.nodeType ) { + owner[ this.expando ] = value; + + // Otherwise secure it in a non-enumerable property + // configurable must be true to allow the property to be + // deleted when data is removed + } else { + Object.defineProperty( owner, this.expando, { + value: value, + configurable: true + } ); + } + } + } + + return value; + }, + set: function( owner, data, value ) { + var prop, + cache = this.cache( owner ); + + // Handle: [ owner, key, value ] args + // Always use camelCase key (gh-2257) + if ( typeof data === "string" ) { + cache[ camelCase( data ) ] = value; + + // Handle: [ owner, { properties } ] args + } else { + + // Copy the properties one-by-one to the cache object + for ( prop in data ) { + cache[ camelCase( prop ) ] = data[ prop ]; + } + } + return cache; + }, + get: function( owner, key ) { + return key === undefined ? + this.cache( owner ) : + + // Always use camelCase key (gh-2257) + owner[ this.expando ] && owner[ this.expando ][ camelCase( key ) ]; + }, + access: function( owner, key, value ) { + + // In cases where either: + // + // 1. No key was specified + // 2. A string key was specified, but no value provided + // + // Take the "read" path and allow the get method to determine + // which value to return, respectively either: + // + // 1. The entire cache object + // 2. The data stored at the key + // + if ( key === undefined || + ( ( key && typeof key === "string" ) && value === undefined ) ) { + + return this.get( owner, key ); + } + + // When the key is not a string, or both a key and value + // are specified, set or extend (existing objects) with either: + // + // 1. An object of properties + // 2. A key and value + // + this.set( owner, key, value ); + + // Since the "set" path can have two possible entry points + // return the expected data based on which path was taken[*] + return value !== undefined ? value : key; + }, + remove: function( owner, key ) { + var i, + cache = owner[ this.expando ]; + + if ( cache === undefined ) { + return; + } + + if ( key !== undefined ) { + + // Support array or space separated string of keys + if ( Array.isArray( key ) ) { + + // If key is an array of keys... + // We always set camelCase keys, so remove that. + key = key.map( camelCase ); + } else { + key = camelCase( key ); + + // If a key with the spaces exists, use it. + // Otherwise, create an array by matching non-whitespace + key = key in cache ? + [ key ] : + ( key.match( rnothtmlwhite ) || [] ); + } + + i = key.length; + + while ( i-- ) { + delete cache[ key[ i ] ]; + } + } + + // Remove the expando if there's no more data + if ( key === undefined || jQuery.isEmptyObject( cache ) ) { + + // Support: Chrome <=35 - 45 + // Webkit & Blink performance suffers when deleting properties + // from DOM nodes, so set to undefined instead + // https://bugs.chromium.org/p/chromium/issues/detail?id=378607 (bug restricted) + if ( owner.nodeType ) { + owner[ this.expando ] = undefined; + } else { + delete owner[ this.expando ]; + } + } + }, + hasData: function( owner ) { + var cache = owner[ this.expando ]; + return cache !== undefined && !jQuery.isEmptyObject( cache ); + } +}; +var dataPriv = new Data(); + +var dataUser = new Data(); + + + +// Implementation Summary +// +// 1. Enforce API surface and semantic compatibility with 1.9.x branch +// 2. Improve the module's maintainability by reducing the storage +// paths to a single mechanism. +// 3. Use the same single mechanism to support "private" and "user" data. +// 4. _Never_ expose "private" data to user code (TODO: Drop _data, _removeData) +// 5. Avoid exposing implementation details on user objects (eg. expando properties) +// 6. Provide a clear path for implementation upgrade to WeakMap in 2014 + +var rbrace = /^(?:\{[\w\W]*\}|\[[\w\W]*\])$/, + rmultiDash = /[A-Z]/g; + +function getData( data ) { + if ( data === "true" ) { + return true; + } + + if ( data === "false" ) { + return false; + } + + if ( data === "null" ) { + return null; + } + + // Only convert to a number if it doesn't change the string + if ( data === +data + "" ) { + return +data; + } + + if ( rbrace.test( data ) ) { + return JSON.parse( data ); + } + + return data; +} + +function dataAttr( elem, key, data ) { + var name; + + // If nothing was found internally, try to fetch any + // data from the HTML5 data-* attribute + if ( data === undefined && elem.nodeType === 1 ) { + name = "data-" + key.replace( rmultiDash, "-$&" ).toLowerCase(); + data = elem.getAttribute( name ); + + if ( typeof data === "string" ) { + try { + data = getData( data ); + } catch ( e ) {} + + // Make sure we set the data so it isn't changed later + dataUser.set( elem, key, data ); + } else { + data = undefined; + } + } + return data; +} + +jQuery.extend( { + hasData: function( elem ) { + return dataUser.hasData( elem ) || dataPriv.hasData( elem ); + }, + + data: function( elem, name, data ) { + return dataUser.access( elem, name, data ); + }, + + removeData: function( elem, name ) { + dataUser.remove( elem, name ); + }, + + // TODO: Now that all calls to _data and _removeData have been replaced + // with direct calls to dataPriv methods, these can be deprecated. + _data: function( elem, name, data ) { + return dataPriv.access( elem, name, data ); + }, + + _removeData: function( elem, name ) { + dataPriv.remove( elem, name ); + } +} ); + +jQuery.fn.extend( { + data: function( key, value ) { + var i, name, data, + elem = this[ 0 ], + attrs = elem && elem.attributes; + + // Gets all values + if ( key === undefined ) { + if ( this.length ) { + data = dataUser.get( elem ); + + if ( elem.nodeType === 1 && !dataPriv.get( elem, "hasDataAttrs" ) ) { + i = attrs.length; + while ( i-- ) { + + // Support: IE 11 only + // The attrs elements can be null (#14894) + if ( attrs[ i ] ) { + name = attrs[ i ].name; + if ( name.indexOf( "data-" ) === 0 ) { + name = camelCase( name.slice( 5 ) ); + dataAttr( elem, name, data[ name ] ); + } + } + } + dataPriv.set( elem, "hasDataAttrs", true ); + } + } + + return data; + } + + // Sets multiple values + if ( typeof key === "object" ) { + return this.each( function() { + dataUser.set( this, key ); + } ); + } + + return access( this, function( value ) { + var data; + + // The calling jQuery object (element matches) is not empty + // (and therefore has an element appears at this[ 0 ]) and the + // `value` parameter was not undefined. An empty jQuery object + // will result in `undefined` for elem = this[ 0 ] which will + // throw an exception if an attempt to read a data cache is made. + if ( elem && value === undefined ) { + + // Attempt to get data from the cache + // The key will always be camelCased in Data + data = dataUser.get( elem, key ); + if ( data !== undefined ) { + return data; + } + + // Attempt to "discover" the data in + // HTML5 custom data-* attrs + data = dataAttr( elem, key ); + if ( data !== undefined ) { + return data; + } + + // We tried really hard, but the data doesn't exist. + return; + } + + // Set the data... + this.each( function() { + + // We always store the camelCased key + dataUser.set( this, key, value ); + } ); + }, null, value, arguments.length > 1, null, true ); + }, + + removeData: function( key ) { + return this.each( function() { + dataUser.remove( this, key ); + } ); + } +} ); + + +jQuery.extend( { + queue: function( elem, type, data ) { + var queue; + + if ( elem ) { + type = ( type || "fx" ) + "queue"; + queue = dataPriv.get( elem, type ); + + // Speed up dequeue by getting out quickly if this is just a lookup + if ( data ) { + if ( !queue || Array.isArray( data ) ) { + queue = dataPriv.access( elem, type, jQuery.makeArray( data ) ); + } else { + queue.push( data ); + } + } + return queue || []; + } + }, + + dequeue: function( elem, type ) { + type = type || "fx"; + + var queue = jQuery.queue( elem, type ), + startLength = queue.length, + fn = queue.shift(), + hooks = jQuery._queueHooks( elem, type ), + next = function() { + jQuery.dequeue( elem, type ); + }; + + // If the fx queue is dequeued, always remove the progress sentinel + if ( fn === "inprogress" ) { + fn = queue.shift(); + startLength--; + } + + if ( fn ) { + + // Add a progress sentinel to prevent the fx queue from being + // automatically dequeued + if ( type === "fx" ) { + queue.unshift( "inprogress" ); + } + + // Clear up the last queue stop function + delete hooks.stop; + fn.call( elem, next, hooks ); + } + + if ( !startLength && hooks ) { + hooks.empty.fire(); + } + }, + + // Not public - generate a queueHooks object, or return the current one + _queueHooks: function( elem, type ) { + var key = type + "queueHooks"; + return dataPriv.get( elem, key ) || dataPriv.access( elem, key, { + empty: jQuery.Callbacks( "once memory" ).add( function() { + dataPriv.remove( elem, [ type + "queue", key ] ); + } ) + } ); + } +} ); + +jQuery.fn.extend( { + queue: function( type, data ) { + var setter = 2; + + if ( typeof type !== "string" ) { + data = type; + type = "fx"; + setter--; + } + + if ( arguments.length < setter ) { + return jQuery.queue( this[ 0 ], type ); + } + + return data === undefined ? + this : + this.each( function() { + var queue = jQuery.queue( this, type, data ); + + // Ensure a hooks for this queue + jQuery._queueHooks( this, type ); + + if ( type === "fx" && queue[ 0 ] !== "inprogress" ) { + jQuery.dequeue( this, type ); + } + } ); + }, + dequeue: function( type ) { + return this.each( function() { + jQuery.dequeue( this, type ); + } ); + }, + clearQueue: function( type ) { + return this.queue( type || "fx", [] ); + }, + + // Get a promise resolved when queues of a certain type + // are emptied (fx is the type by default) + promise: function( type, obj ) { + var tmp, + count = 1, + defer = jQuery.Deferred(), + elements = this, + i = this.length, + resolve = function() { + if ( !( --count ) ) { + defer.resolveWith( elements, [ elements ] ); + } + }; + + if ( typeof type !== "string" ) { + obj = type; + type = undefined; + } + type = type || "fx"; + + while ( i-- ) { + tmp = dataPriv.get( elements[ i ], type + "queueHooks" ); + if ( tmp && tmp.empty ) { + count++; + tmp.empty.add( resolve ); + } + } + resolve(); + return defer.promise( obj ); + } +} ); +var pnum = ( /[+-]?(?:\d*\.|)\d+(?:[eE][+-]?\d+|)/ ).source; + +var rcssNum = new RegExp( "^(?:([+-])=|)(" + pnum + ")([a-z%]*)$", "i" ); + + +var cssExpand = [ "Top", "Right", "Bottom", "Left" ]; + +var documentElement = document.documentElement; + + + + var isAttached = function( elem ) { + return jQuery.contains( elem.ownerDocument, elem ); + }, + composed = { composed: true }; + + // Support: IE 9 - 11+, Edge 12 - 18+, iOS 10.0 - 10.2 only + // Check attachment across shadow DOM boundaries when possible (gh-3504) + // Support: iOS 10.0-10.2 only + // Early iOS 10 versions support `attachShadow` but not `getRootNode`, + // leading to errors. We need to check for `getRootNode`. + if ( documentElement.getRootNode ) { + isAttached = function( elem ) { + return jQuery.contains( elem.ownerDocument, elem ) || + elem.getRootNode( composed ) === elem.ownerDocument; + }; + } +var isHiddenWithinTree = function( elem, el ) { + + // isHiddenWithinTree might be called from jQuery#filter function; + // in that case, element will be second argument + elem = el || elem; + + // Inline style trumps all + return elem.style.display === "none" || + elem.style.display === "" && + + // Otherwise, check computed style + // Support: Firefox <=43 - 45 + // Disconnected elements can have computed display: none, so first confirm that elem is + // in the document. + isAttached( elem ) && + + jQuery.css( elem, "display" ) === "none"; + }; + + + +function adjustCSS( elem, prop, valueParts, tween ) { + var adjusted, scale, + maxIterations = 20, + currentValue = tween ? + function() { + return tween.cur(); + } : + function() { + return jQuery.css( elem, prop, "" ); + }, + initial = currentValue(), + unit = valueParts && valueParts[ 3 ] || ( jQuery.cssNumber[ prop ] ? "" : "px" ), + + // Starting value computation is required for potential unit mismatches + initialInUnit = elem.nodeType && + ( jQuery.cssNumber[ prop ] || unit !== "px" && +initial ) && + rcssNum.exec( jQuery.css( elem, prop ) ); + + if ( initialInUnit && initialInUnit[ 3 ] !== unit ) { + + // Support: Firefox <=54 + // Halve the iteration target value to prevent interference from CSS upper bounds (gh-2144) + initial = initial / 2; + + // Trust units reported by jQuery.css + unit = unit || initialInUnit[ 3 ]; + + // Iteratively approximate from a nonzero starting point + initialInUnit = +initial || 1; + + while ( maxIterations-- ) { + + // Evaluate and update our best guess (doubling guesses that zero out). + // Finish if the scale equals or crosses 1 (making the old*new product non-positive). + jQuery.style( elem, prop, initialInUnit + unit ); + if ( ( 1 - scale ) * ( 1 - ( scale = currentValue() / initial || 0.5 ) ) <= 0 ) { + maxIterations = 0; + } + initialInUnit = initialInUnit / scale; + + } + + initialInUnit = initialInUnit * 2; + jQuery.style( elem, prop, initialInUnit + unit ); + + // Make sure we update the tween properties later on + valueParts = valueParts || []; + } + + if ( valueParts ) { + initialInUnit = +initialInUnit || +initial || 0; + + // Apply relative offset (+=/-=) if specified + adjusted = valueParts[ 1 ] ? + initialInUnit + ( valueParts[ 1 ] + 1 ) * valueParts[ 2 ] : + +valueParts[ 2 ]; + if ( tween ) { + tween.unit = unit; + tween.start = initialInUnit; + tween.end = adjusted; + } + } + return adjusted; +} + + +var defaultDisplayMap = {}; + +function getDefaultDisplay( elem ) { + var temp, + doc = elem.ownerDocument, + nodeName = elem.nodeName, + display = defaultDisplayMap[ nodeName ]; + + if ( display ) { + return display; + } + + temp = doc.body.appendChild( doc.createElement( nodeName ) ); + display = jQuery.css( temp, "display" ); + + temp.parentNode.removeChild( temp ); + + if ( display === "none" ) { + display = "block"; + } + defaultDisplayMap[ nodeName ] = display; + + return display; +} + +function showHide( elements, show ) { + var display, elem, + values = [], + index = 0, + length = elements.length; + + // Determine new display value for elements that need to change + for ( ; index < length; index++ ) { + elem = elements[ index ]; + if ( !elem.style ) { + continue; + } + + display = elem.style.display; + if ( show ) { + + // Since we force visibility upon cascade-hidden elements, an immediate (and slow) + // check is required in this first loop unless we have a nonempty display value (either + // inline or about-to-be-restored) + if ( display === "none" ) { + values[ index ] = dataPriv.get( elem, "display" ) || null; + if ( !values[ index ] ) { + elem.style.display = ""; + } + } + if ( elem.style.display === "" && isHiddenWithinTree( elem ) ) { + values[ index ] = getDefaultDisplay( elem ); + } + } else { + if ( display !== "none" ) { + values[ index ] = "none"; + + // Remember what we're overwriting + dataPriv.set( elem, "display", display ); + } + } + } + + // Set the display of the elements in a second loop to avoid constant reflow + for ( index = 0; index < length; index++ ) { + if ( values[ index ] != null ) { + elements[ index ].style.display = values[ index ]; + } + } + + return elements; +} + +jQuery.fn.extend( { + show: function() { + return showHide( this, true ); + }, + hide: function() { + return showHide( this ); + }, + toggle: function( state ) { + if ( typeof state === "boolean" ) { + return state ? this.show() : this.hide(); + } + + return this.each( function() { + if ( isHiddenWithinTree( this ) ) { + jQuery( this ).show(); + } else { + jQuery( this ).hide(); + } + } ); + } +} ); +var rcheckableType = ( /^(?:checkbox|radio)$/i ); + +var rtagName = ( /<([a-z][^\/\0>\x20\t\r\n\f]*)/i ); + +var rscriptType = ( /^$|^module$|\/(?:java|ecma)script/i ); + + + +( function() { + var fragment = document.createDocumentFragment(), + div = fragment.appendChild( document.createElement( "div" ) ), + input = document.createElement( "input" ); + + // Support: Android 4.0 - 4.3 only + // Check state lost if the name is set (#11217) + // Support: Windows Web Apps (WWA) + // `name` and `type` must use .setAttribute for WWA (#14901) + input.setAttribute( "type", "radio" ); + input.setAttribute( "checked", "checked" ); + input.setAttribute( "name", "t" ); + + div.appendChild( input ); + + // Support: Android <=4.1 only + // Older WebKit doesn't clone checked state correctly in fragments + support.checkClone = div.cloneNode( true ).cloneNode( true ).lastChild.checked; + + // Support: IE <=11 only + // Make sure textarea (and checkbox) defaultValue is properly cloned + div.innerHTML = ""; + support.noCloneChecked = !!div.cloneNode( true ).lastChild.defaultValue; + + // Support: IE <=9 only + // IE <=9 replaces "; + support.option = !!div.lastChild; +} )(); + + +// We have to close these tags to support XHTML (#13200) +var wrapMap = { + + // XHTML parsers do not magically insert elements in the + // same way that tag soup parsers do. So we cannot shorten + // this by omitting or other required elements. + thead: [ 1, "", "
" ], + col: [ 2, "", "
" ], + tr: [ 2, "", "
" ], + td: [ 3, "", "
" ], + + _default: [ 0, "", "" ] +}; + +wrapMap.tbody = wrapMap.tfoot = wrapMap.colgroup = wrapMap.caption = wrapMap.thead; +wrapMap.th = wrapMap.td; + +// Support: IE <=9 only +if ( !support.option ) { + wrapMap.optgroup = wrapMap.option = [ 1, "" ]; +} + + +function getAll( context, tag ) { + + // Support: IE <=9 - 11 only + // Use typeof to avoid zero-argument method invocation on host objects (#15151) + var ret; + + if ( typeof context.getElementsByTagName !== "undefined" ) { + ret = context.getElementsByTagName( tag || "*" ); + + } else if ( typeof context.querySelectorAll !== "undefined" ) { + ret = context.querySelectorAll( tag || "*" ); + + } else { + ret = []; + } + + if ( tag === undefined || tag && nodeName( context, tag ) ) { + return jQuery.merge( [ context ], ret ); + } + + return ret; +} + + +// Mark scripts as having already been evaluated +function setGlobalEval( elems, refElements ) { + var i = 0, + l = elems.length; + + for ( ; i < l; i++ ) { + dataPriv.set( + elems[ i ], + "globalEval", + !refElements || dataPriv.get( refElements[ i ], "globalEval" ) + ); + } +} + + +var rhtml = /<|&#?\w+;/; + +function buildFragment( elems, context, scripts, selection, ignored ) { + var elem, tmp, tag, wrap, attached, j, + fragment = context.createDocumentFragment(), + nodes = [], + i = 0, + l = elems.length; + + for ( ; i < l; i++ ) { + elem = elems[ i ]; + + if ( elem || elem === 0 ) { + + // Add nodes directly + if ( toType( elem ) === "object" ) { + + // Support: Android <=4.0 only, PhantomJS 1 only + // push.apply(_, arraylike) throws on ancient WebKit + jQuery.merge( nodes, elem.nodeType ? [ elem ] : elem ); + + // Convert non-html into a text node + } else if ( !rhtml.test( elem ) ) { + nodes.push( context.createTextNode( elem ) ); + + // Convert html into DOM nodes + } else { + tmp = tmp || fragment.appendChild( context.createElement( "div" ) ); + + // Deserialize a standard representation + tag = ( rtagName.exec( elem ) || [ "", "" ] )[ 1 ].toLowerCase(); + wrap = wrapMap[ tag ] || wrapMap._default; + tmp.innerHTML = wrap[ 1 ] + jQuery.htmlPrefilter( elem ) + wrap[ 2 ]; + + // Descend through wrappers to the right content + j = wrap[ 0 ]; + while ( j-- ) { + tmp = tmp.lastChild; + } + + // Support: Android <=4.0 only, PhantomJS 1 only + // push.apply(_, arraylike) throws on ancient WebKit + jQuery.merge( nodes, tmp.childNodes ); + + // Remember the top-level container + tmp = fragment.firstChild; + + // Ensure the created nodes are orphaned (#12392) + tmp.textContent = ""; + } + } + } + + // Remove wrapper from fragment + fragment.textContent = ""; + + i = 0; + while ( ( elem = nodes[ i++ ] ) ) { + + // Skip elements already in the context collection (trac-4087) + if ( selection && jQuery.inArray( elem, selection ) > -1 ) { + if ( ignored ) { + ignored.push( elem ); + } + continue; + } + + attached = isAttached( elem ); + + // Append to fragment + tmp = getAll( fragment.appendChild( elem ), "script" ); + + // Preserve script evaluation history + if ( attached ) { + setGlobalEval( tmp ); + } + + // Capture executables + if ( scripts ) { + j = 0; + while ( ( elem = tmp[ j++ ] ) ) { + if ( rscriptType.test( elem.type || "" ) ) { + scripts.push( elem ); + } + } + } + } + + return fragment; +} + + +var rtypenamespace = /^([^.]*)(?:\.(.+)|)/; + +function returnTrue() { + return true; +} + +function returnFalse() { + return false; +} + +// Support: IE <=9 - 11+ +// focus() and blur() are asynchronous, except when they are no-op. +// So expect focus to be synchronous when the element is already active, +// and blur to be synchronous when the element is not already active. +// (focus and blur are always synchronous in other supported browsers, +// this just defines when we can count on it). +function expectSync( elem, type ) { + return ( elem === safeActiveElement() ) === ( type === "focus" ); +} + +// Support: IE <=9 only +// Accessing document.activeElement can throw unexpectedly +// https://bugs.jquery.com/ticket/13393 +function safeActiveElement() { + try { + return document.activeElement; + } catch ( err ) { } +} + +function on( elem, types, selector, data, fn, one ) { + var origFn, type; + + // Types can be a map of types/handlers + if ( typeof types === "object" ) { + + // ( types-Object, selector, data ) + if ( typeof selector !== "string" ) { + + // ( types-Object, data ) + data = data || selector; + selector = undefined; + } + for ( type in types ) { + on( elem, type, selector, data, types[ type ], one ); + } + return elem; + } + + if ( data == null && fn == null ) { + + // ( types, fn ) + fn = selector; + data = selector = undefined; + } else if ( fn == null ) { + if ( typeof selector === "string" ) { + + // ( types, selector, fn ) + fn = data; + data = undefined; + } else { + + // ( types, data, fn ) + fn = data; + data = selector; + selector = undefined; + } + } + if ( fn === false ) { + fn = returnFalse; + } else if ( !fn ) { + return elem; + } + + if ( one === 1 ) { + origFn = fn; + fn = function( event ) { + + // Can use an empty set, since event contains the info + jQuery().off( event ); + return origFn.apply( this, arguments ); + }; + + // Use same guid so caller can remove using origFn + fn.guid = origFn.guid || ( origFn.guid = jQuery.guid++ ); + } + return elem.each( function() { + jQuery.event.add( this, types, fn, data, selector ); + } ); +} + +/* + * Helper functions for managing events -- not part of the public interface. + * Props to Dean Edwards' addEvent library for many of the ideas. + */ +jQuery.event = { + + global: {}, + + add: function( elem, types, handler, data, selector ) { + + var handleObjIn, eventHandle, tmp, + events, t, handleObj, + special, handlers, type, namespaces, origType, + elemData = dataPriv.get( elem ); + + // Only attach events to objects that accept data + if ( !acceptData( elem ) ) { + return; + } + + // Caller can pass in an object of custom data in lieu of the handler + if ( handler.handler ) { + handleObjIn = handler; + handler = handleObjIn.handler; + selector = handleObjIn.selector; + } + + // Ensure that invalid selectors throw exceptions at attach time + // Evaluate against documentElement in case elem is a non-element node (e.g., document) + if ( selector ) { + jQuery.find.matchesSelector( documentElement, selector ); + } + + // Make sure that the handler has a unique ID, used to find/remove it later + if ( !handler.guid ) { + handler.guid = jQuery.guid++; + } + + // Init the element's event structure and main handler, if this is the first + if ( !( events = elemData.events ) ) { + events = elemData.events = Object.create( null ); + } + if ( !( eventHandle = elemData.handle ) ) { + eventHandle = elemData.handle = function( e ) { + + // Discard the second event of a jQuery.event.trigger() and + // when an event is called after a page has unloaded + return typeof jQuery !== "undefined" && jQuery.event.triggered !== e.type ? + jQuery.event.dispatch.apply( elem, arguments ) : undefined; + }; + } + + // Handle multiple events separated by a space + types = ( types || "" ).match( rnothtmlwhite ) || [ "" ]; + t = types.length; + while ( t-- ) { + tmp = rtypenamespace.exec( types[ t ] ) || []; + type = origType = tmp[ 1 ]; + namespaces = ( tmp[ 2 ] || "" ).split( "." ).sort(); + + // There *must* be a type, no attaching namespace-only handlers + if ( !type ) { + continue; + } + + // If event changes its type, use the special event handlers for the changed type + special = jQuery.event.special[ type ] || {}; + + // If selector defined, determine special event api type, otherwise given type + type = ( selector ? special.delegateType : special.bindType ) || type; + + // Update special based on newly reset type + special = jQuery.event.special[ type ] || {}; + + // handleObj is passed to all event handlers + handleObj = jQuery.extend( { + type: type, + origType: origType, + data: data, + handler: handler, + guid: handler.guid, + selector: selector, + needsContext: selector && jQuery.expr.match.needsContext.test( selector ), + namespace: namespaces.join( "." ) + }, handleObjIn ); + + // Init the event handler queue if we're the first + if ( !( handlers = events[ type ] ) ) { + handlers = events[ type ] = []; + handlers.delegateCount = 0; + + // Only use addEventListener if the special events handler returns false + if ( !special.setup || + special.setup.call( elem, data, namespaces, eventHandle ) === false ) { + + if ( elem.addEventListener ) { + elem.addEventListener( type, eventHandle ); + } + } + } + + if ( special.add ) { + special.add.call( elem, handleObj ); + + if ( !handleObj.handler.guid ) { + handleObj.handler.guid = handler.guid; + } + } + + // Add to the element's handler list, delegates in front + if ( selector ) { + handlers.splice( handlers.delegateCount++, 0, handleObj ); + } else { + handlers.push( handleObj ); + } + + // Keep track of which events have ever been used, for event optimization + jQuery.event.global[ type ] = true; + } + + }, + + // Detach an event or set of events from an element + remove: function( elem, types, handler, selector, mappedTypes ) { + + var j, origCount, tmp, + events, t, handleObj, + special, handlers, type, namespaces, origType, + elemData = dataPriv.hasData( elem ) && dataPriv.get( elem ); + + if ( !elemData || !( events = elemData.events ) ) { + return; + } + + // Once for each type.namespace in types; type may be omitted + types = ( types || "" ).match( rnothtmlwhite ) || [ "" ]; + t = types.length; + while ( t-- ) { + tmp = rtypenamespace.exec( types[ t ] ) || []; + type = origType = tmp[ 1 ]; + namespaces = ( tmp[ 2 ] || "" ).split( "." ).sort(); + + // Unbind all events (on this namespace, if provided) for the element + if ( !type ) { + for ( type in events ) { + jQuery.event.remove( elem, type + types[ t ], handler, selector, true ); + } + continue; + } + + special = jQuery.event.special[ type ] || {}; + type = ( selector ? special.delegateType : special.bindType ) || type; + handlers = events[ type ] || []; + tmp = tmp[ 2 ] && + new RegExp( "(^|\\.)" + namespaces.join( "\\.(?:.*\\.|)" ) + "(\\.|$)" ); + + // Remove matching events + origCount = j = handlers.length; + while ( j-- ) { + handleObj = handlers[ j ]; + + if ( ( mappedTypes || origType === handleObj.origType ) && + ( !handler || handler.guid === handleObj.guid ) && + ( !tmp || tmp.test( handleObj.namespace ) ) && + ( !selector || selector === handleObj.selector || + selector === "**" && handleObj.selector ) ) { + handlers.splice( j, 1 ); + + if ( handleObj.selector ) { + handlers.delegateCount--; + } + if ( special.remove ) { + special.remove.call( elem, handleObj ); + } + } + } + + // Remove generic event handler if we removed something and no more handlers exist + // (avoids potential for endless recursion during removal of special event handlers) + if ( origCount && !handlers.length ) { + if ( !special.teardown || + special.teardown.call( elem, namespaces, elemData.handle ) === false ) { + + jQuery.removeEvent( elem, type, elemData.handle ); + } + + delete events[ type ]; + } + } + + // Remove data and the expando if it's no longer used + if ( jQuery.isEmptyObject( events ) ) { + dataPriv.remove( elem, "handle events" ); + } + }, + + dispatch: function( nativeEvent ) { + + var i, j, ret, matched, handleObj, handlerQueue, + args = new Array( arguments.length ), + + // Make a writable jQuery.Event from the native event object + event = jQuery.event.fix( nativeEvent ), + + handlers = ( + dataPriv.get( this, "events" ) || Object.create( null ) + )[ event.type ] || [], + special = jQuery.event.special[ event.type ] || {}; + + // Use the fix-ed jQuery.Event rather than the (read-only) native event + args[ 0 ] = event; + + for ( i = 1; i < arguments.length; i++ ) { + args[ i ] = arguments[ i ]; + } + + event.delegateTarget = this; + + // Call the preDispatch hook for the mapped type, and let it bail if desired + if ( special.preDispatch && special.preDispatch.call( this, event ) === false ) { + return; + } + + // Determine handlers + handlerQueue = jQuery.event.handlers.call( this, event, handlers ); + + // Run delegates first; they may want to stop propagation beneath us + i = 0; + while ( ( matched = handlerQueue[ i++ ] ) && !event.isPropagationStopped() ) { + event.currentTarget = matched.elem; + + j = 0; + while ( ( handleObj = matched.handlers[ j++ ] ) && + !event.isImmediatePropagationStopped() ) { + + // If the event is namespaced, then each handler is only invoked if it is + // specially universal or its namespaces are a superset of the event's. + if ( !event.rnamespace || handleObj.namespace === false || + event.rnamespace.test( handleObj.namespace ) ) { + + event.handleObj = handleObj; + event.data = handleObj.data; + + ret = ( ( jQuery.event.special[ handleObj.origType ] || {} ).handle || + handleObj.handler ).apply( matched.elem, args ); + + if ( ret !== undefined ) { + if ( ( event.result = ret ) === false ) { + event.preventDefault(); + event.stopPropagation(); + } + } + } + } + } + + // Call the postDispatch hook for the mapped type + if ( special.postDispatch ) { + special.postDispatch.call( this, event ); + } + + return event.result; + }, + + handlers: function( event, handlers ) { + var i, handleObj, sel, matchedHandlers, matchedSelectors, + handlerQueue = [], + delegateCount = handlers.delegateCount, + cur = event.target; + + // Find delegate handlers + if ( delegateCount && + + // Support: IE <=9 + // Black-hole SVG instance trees (trac-13180) + cur.nodeType && + + // Support: Firefox <=42 + // Suppress spec-violating clicks indicating a non-primary pointer button (trac-3861) + // https://www.w3.org/TR/DOM-Level-3-Events/#event-type-click + // Support: IE 11 only + // ...but not arrow key "clicks" of radio inputs, which can have `button` -1 (gh-2343) + !( event.type === "click" && event.button >= 1 ) ) { + + for ( ; cur !== this; cur = cur.parentNode || this ) { + + // Don't check non-elements (#13208) + // Don't process clicks on disabled elements (#6911, #8165, #11382, #11764) + if ( cur.nodeType === 1 && !( event.type === "click" && cur.disabled === true ) ) { + matchedHandlers = []; + matchedSelectors = {}; + for ( i = 0; i < delegateCount; i++ ) { + handleObj = handlers[ i ]; + + // Don't conflict with Object.prototype properties (#13203) + sel = handleObj.selector + " "; + + if ( matchedSelectors[ sel ] === undefined ) { + matchedSelectors[ sel ] = handleObj.needsContext ? + jQuery( sel, this ).index( cur ) > -1 : + jQuery.find( sel, this, null, [ cur ] ).length; + } + if ( matchedSelectors[ sel ] ) { + matchedHandlers.push( handleObj ); + } + } + if ( matchedHandlers.length ) { + handlerQueue.push( { elem: cur, handlers: matchedHandlers } ); + } + } + } + } + + // Add the remaining (directly-bound) handlers + cur = this; + if ( delegateCount < handlers.length ) { + handlerQueue.push( { elem: cur, handlers: handlers.slice( delegateCount ) } ); + } + + return handlerQueue; + }, + + addProp: function( name, hook ) { + Object.defineProperty( jQuery.Event.prototype, name, { + enumerable: true, + configurable: true, + + get: isFunction( hook ) ? + function() { + if ( this.originalEvent ) { + return hook( this.originalEvent ); + } + } : + function() { + if ( this.originalEvent ) { + return this.originalEvent[ name ]; + } + }, + + set: function( value ) { + Object.defineProperty( this, name, { + enumerable: true, + configurable: true, + writable: true, + value: value + } ); + } + } ); + }, + + fix: function( originalEvent ) { + return originalEvent[ jQuery.expando ] ? + originalEvent : + new jQuery.Event( originalEvent ); + }, + + special: { + load: { + + // Prevent triggered image.load events from bubbling to window.load + noBubble: true + }, + click: { + + // Utilize native event to ensure correct state for checkable inputs + setup: function( data ) { + + // For mutual compressibility with _default, replace `this` access with a local var. + // `|| data` is dead code meant only to preserve the variable through minification. + var el = this || data; + + // Claim the first handler + if ( rcheckableType.test( el.type ) && + el.click && nodeName( el, "input" ) ) { + + // dataPriv.set( el, "click", ... ) + leverageNative( el, "click", returnTrue ); + } + + // Return false to allow normal processing in the caller + return false; + }, + trigger: function( data ) { + + // For mutual compressibility with _default, replace `this` access with a local var. + // `|| data` is dead code meant only to preserve the variable through minification. + var el = this || data; + + // Force setup before triggering a click + if ( rcheckableType.test( el.type ) && + el.click && nodeName( el, "input" ) ) { + + leverageNative( el, "click" ); + } + + // Return non-false to allow normal event-path propagation + return true; + }, + + // For cross-browser consistency, suppress native .click() on links + // Also prevent it if we're currently inside a leveraged native-event stack + _default: function( event ) { + var target = event.target; + return rcheckableType.test( target.type ) && + target.click && nodeName( target, "input" ) && + dataPriv.get( target, "click" ) || + nodeName( target, "a" ); + } + }, + + beforeunload: { + postDispatch: function( event ) { + + // Support: Firefox 20+ + // Firefox doesn't alert if the returnValue field is not set. + if ( event.result !== undefined && event.originalEvent ) { + event.originalEvent.returnValue = event.result; + } + } + } + } +}; + +// Ensure the presence of an event listener that handles manually-triggered +// synthetic events by interrupting progress until reinvoked in response to +// *native* events that it fires directly, ensuring that state changes have +// already occurred before other listeners are invoked. +function leverageNative( el, type, expectSync ) { + + // Missing expectSync indicates a trigger call, which must force setup through jQuery.event.add + if ( !expectSync ) { + if ( dataPriv.get( el, type ) === undefined ) { + jQuery.event.add( el, type, returnTrue ); + } + return; + } + + // Register the controller as a special universal handler for all event namespaces + dataPriv.set( el, type, false ); + jQuery.event.add( el, type, { + namespace: false, + handler: function( event ) { + var notAsync, result, + saved = dataPriv.get( this, type ); + + if ( ( event.isTrigger & 1 ) && this[ type ] ) { + + // Interrupt processing of the outer synthetic .trigger()ed event + // Saved data should be false in such cases, but might be a leftover capture object + // from an async native handler (gh-4350) + if ( !saved.length ) { + + // Store arguments for use when handling the inner native event + // There will always be at least one argument (an event object), so this array + // will not be confused with a leftover capture object. + saved = slice.call( arguments ); + dataPriv.set( this, type, saved ); + + // Trigger the native event and capture its result + // Support: IE <=9 - 11+ + // focus() and blur() are asynchronous + notAsync = expectSync( this, type ); + this[ type ](); + result = dataPriv.get( this, type ); + if ( saved !== result || notAsync ) { + dataPriv.set( this, type, false ); + } else { + result = {}; + } + if ( saved !== result ) { + + // Cancel the outer synthetic event + event.stopImmediatePropagation(); + event.preventDefault(); + + // Support: Chrome 86+ + // In Chrome, if an element having a focusout handler is blurred by + // clicking outside of it, it invokes the handler synchronously. If + // that handler calls `.remove()` on the element, the data is cleared, + // leaving `result` undefined. We need to guard against this. + return result && result.value; + } + + // If this is an inner synthetic event for an event with a bubbling surrogate + // (focus or blur), assume that the surrogate already propagated from triggering the + // native event and prevent that from happening again here. + // This technically gets the ordering wrong w.r.t. to `.trigger()` (in which the + // bubbling surrogate propagates *after* the non-bubbling base), but that seems + // less bad than duplication. + } else if ( ( jQuery.event.special[ type ] || {} ).delegateType ) { + event.stopPropagation(); + } + + // If this is a native event triggered above, everything is now in order + // Fire an inner synthetic event with the original arguments + } else if ( saved.length ) { + + // ...and capture the result + dataPriv.set( this, type, { + value: jQuery.event.trigger( + + // Support: IE <=9 - 11+ + // Extend with the prototype to reset the above stopImmediatePropagation() + jQuery.extend( saved[ 0 ], jQuery.Event.prototype ), + saved.slice( 1 ), + this + ) + } ); + + // Abort handling of the native event + event.stopImmediatePropagation(); + } + } + } ); +} + +jQuery.removeEvent = function( elem, type, handle ) { + + // This "if" is needed for plain objects + if ( elem.removeEventListener ) { + elem.removeEventListener( type, handle ); + } +}; + +jQuery.Event = function( src, props ) { + + // Allow instantiation without the 'new' keyword + if ( !( this instanceof jQuery.Event ) ) { + return new jQuery.Event( src, props ); + } + + // Event object + if ( src && src.type ) { + this.originalEvent = src; + this.type = src.type; + + // Events bubbling up the document may have been marked as prevented + // by a handler lower down the tree; reflect the correct value. + this.isDefaultPrevented = src.defaultPrevented || + src.defaultPrevented === undefined && + + // Support: Android <=2.3 only + src.returnValue === false ? + returnTrue : + returnFalse; + + // Create target properties + // Support: Safari <=6 - 7 only + // Target should not be a text node (#504, #13143) + this.target = ( src.target && src.target.nodeType === 3 ) ? + src.target.parentNode : + src.target; + + this.currentTarget = src.currentTarget; + this.relatedTarget = src.relatedTarget; + + // Event type + } else { + this.type = src; + } + + // Put explicitly provided properties onto the event object + if ( props ) { + jQuery.extend( this, props ); + } + + // Create a timestamp if incoming event doesn't have one + this.timeStamp = src && src.timeStamp || Date.now(); + + // Mark it as fixed + this[ jQuery.expando ] = true; +}; + +// jQuery.Event is based on DOM3 Events as specified by the ECMAScript Language Binding +// https://www.w3.org/TR/2003/WD-DOM-Level-3-Events-20030331/ecma-script-binding.html +jQuery.Event.prototype = { + constructor: jQuery.Event, + isDefaultPrevented: returnFalse, + isPropagationStopped: returnFalse, + isImmediatePropagationStopped: returnFalse, + isSimulated: false, + + preventDefault: function() { + var e = this.originalEvent; + + this.isDefaultPrevented = returnTrue; + + if ( e && !this.isSimulated ) { + e.preventDefault(); + } + }, + stopPropagation: function() { + var e = this.originalEvent; + + this.isPropagationStopped = returnTrue; + + if ( e && !this.isSimulated ) { + e.stopPropagation(); + } + }, + stopImmediatePropagation: function() { + var e = this.originalEvent; + + this.isImmediatePropagationStopped = returnTrue; + + if ( e && !this.isSimulated ) { + e.stopImmediatePropagation(); + } + + this.stopPropagation(); + } +}; + +// Includes all common event props including KeyEvent and MouseEvent specific props +jQuery.each( { + altKey: true, + bubbles: true, + cancelable: true, + changedTouches: true, + ctrlKey: true, + detail: true, + eventPhase: true, + metaKey: true, + pageX: true, + pageY: true, + shiftKey: true, + view: true, + "char": true, + code: true, + charCode: true, + key: true, + keyCode: true, + button: true, + buttons: true, + clientX: true, + clientY: true, + offsetX: true, + offsetY: true, + pointerId: true, + pointerType: true, + screenX: true, + screenY: true, + targetTouches: true, + toElement: true, + touches: true, + which: true +}, jQuery.event.addProp ); + +jQuery.each( { focus: "focusin", blur: "focusout" }, function( type, delegateType ) { + jQuery.event.special[ type ] = { + + // Utilize native event if possible so blur/focus sequence is correct + setup: function() { + + // Claim the first handler + // dataPriv.set( this, "focus", ... ) + // dataPriv.set( this, "blur", ... ) + leverageNative( this, type, expectSync ); + + // Return false to allow normal processing in the caller + return false; + }, + trigger: function() { + + // Force setup before trigger + leverageNative( this, type ); + + // Return non-false to allow normal event-path propagation + return true; + }, + + // Suppress native focus or blur as it's already being fired + // in leverageNative. + _default: function() { + return true; + }, + + delegateType: delegateType + }; +} ); + +// Create mouseenter/leave events using mouseover/out and event-time checks +// so that event delegation works in jQuery. +// Do the same for pointerenter/pointerleave and pointerover/pointerout +// +// Support: Safari 7 only +// Safari sends mouseenter too often; see: +// https://bugs.chromium.org/p/chromium/issues/detail?id=470258 +// for the description of the bug (it existed in older Chrome versions as well). +jQuery.each( { + mouseenter: "mouseover", + mouseleave: "mouseout", + pointerenter: "pointerover", + pointerleave: "pointerout" +}, function( orig, fix ) { + jQuery.event.special[ orig ] = { + delegateType: fix, + bindType: fix, + + handle: function( event ) { + var ret, + target = this, + related = event.relatedTarget, + handleObj = event.handleObj; + + // For mouseenter/leave call the handler if related is outside the target. + // NB: No relatedTarget if the mouse left/entered the browser window + if ( !related || ( related !== target && !jQuery.contains( target, related ) ) ) { + event.type = handleObj.origType; + ret = handleObj.handler.apply( this, arguments ); + event.type = fix; + } + return ret; + } + }; +} ); + +jQuery.fn.extend( { + + on: function( types, selector, data, fn ) { + return on( this, types, selector, data, fn ); + }, + one: function( types, selector, data, fn ) { + return on( this, types, selector, data, fn, 1 ); + }, + off: function( types, selector, fn ) { + var handleObj, type; + if ( types && types.preventDefault && types.handleObj ) { + + // ( event ) dispatched jQuery.Event + handleObj = types.handleObj; + jQuery( types.delegateTarget ).off( + handleObj.namespace ? + handleObj.origType + "." + handleObj.namespace : + handleObj.origType, + handleObj.selector, + handleObj.handler + ); + return this; + } + if ( typeof types === "object" ) { + + // ( types-object [, selector] ) + for ( type in types ) { + this.off( type, selector, types[ type ] ); + } + return this; + } + if ( selector === false || typeof selector === "function" ) { + + // ( types [, fn] ) + fn = selector; + selector = undefined; + } + if ( fn === false ) { + fn = returnFalse; + } + return this.each( function() { + jQuery.event.remove( this, types, fn, selector ); + } ); + } +} ); + + +var + + // Support: IE <=10 - 11, Edge 12 - 13 only + // In IE/Edge using regex groups here causes severe slowdowns. + // See https://connect.microsoft.com/IE/feedback/details/1736512/ + rnoInnerhtml = /\s*$/g; + +// Prefer a tbody over its parent table for containing new rows +function manipulationTarget( elem, content ) { + if ( nodeName( elem, "table" ) && + nodeName( content.nodeType !== 11 ? content : content.firstChild, "tr" ) ) { + + return jQuery( elem ).children( "tbody" )[ 0 ] || elem; + } + + return elem; +} + +// Replace/restore the type attribute of script elements for safe DOM manipulation +function disableScript( elem ) { + elem.type = ( elem.getAttribute( "type" ) !== null ) + "/" + elem.type; + return elem; +} +function restoreScript( elem ) { + if ( ( elem.type || "" ).slice( 0, 5 ) === "true/" ) { + elem.type = elem.type.slice( 5 ); + } else { + elem.removeAttribute( "type" ); + } + + return elem; +} + +function cloneCopyEvent( src, dest ) { + var i, l, type, pdataOld, udataOld, udataCur, events; + + if ( dest.nodeType !== 1 ) { + return; + } + + // 1. Copy private data: events, handlers, etc. + if ( dataPriv.hasData( src ) ) { + pdataOld = dataPriv.get( src ); + events = pdataOld.events; + + if ( events ) { + dataPriv.remove( dest, "handle events" ); + + for ( type in events ) { + for ( i = 0, l = events[ type ].length; i < l; i++ ) { + jQuery.event.add( dest, type, events[ type ][ i ] ); + } + } + } + } + + // 2. Copy user data + if ( dataUser.hasData( src ) ) { + udataOld = dataUser.access( src ); + udataCur = jQuery.extend( {}, udataOld ); + + dataUser.set( dest, udataCur ); + } +} + +// Fix IE bugs, see support tests +function fixInput( src, dest ) { + var nodeName = dest.nodeName.toLowerCase(); + + // Fails to persist the checked state of a cloned checkbox or radio button. + if ( nodeName === "input" && rcheckableType.test( src.type ) ) { + dest.checked = src.checked; + + // Fails to return the selected option to the default selected state when cloning options + } else if ( nodeName === "input" || nodeName === "textarea" ) { + dest.defaultValue = src.defaultValue; + } +} + +function domManip( collection, args, callback, ignored ) { + + // Flatten any nested arrays + args = flat( args ); + + var fragment, first, scripts, hasScripts, node, doc, + i = 0, + l = collection.length, + iNoClone = l - 1, + value = args[ 0 ], + valueIsFunction = isFunction( value ); + + // We can't cloneNode fragments that contain checked, in WebKit + if ( valueIsFunction || + ( l > 1 && typeof value === "string" && + !support.checkClone && rchecked.test( value ) ) ) { + return collection.each( function( index ) { + var self = collection.eq( index ); + if ( valueIsFunction ) { + args[ 0 ] = value.call( this, index, self.html() ); + } + domManip( self, args, callback, ignored ); + } ); + } + + if ( l ) { + fragment = buildFragment( args, collection[ 0 ].ownerDocument, false, collection, ignored ); + first = fragment.firstChild; + + if ( fragment.childNodes.length === 1 ) { + fragment = first; + } + + // Require either new content or an interest in ignored elements to invoke the callback + if ( first || ignored ) { + scripts = jQuery.map( getAll( fragment, "script" ), disableScript ); + hasScripts = scripts.length; + + // Use the original fragment for the last item + // instead of the first because it can end up + // being emptied incorrectly in certain situations (#8070). + for ( ; i < l; i++ ) { + node = fragment; + + if ( i !== iNoClone ) { + node = jQuery.clone( node, true, true ); + + // Keep references to cloned scripts for later restoration + if ( hasScripts ) { + + // Support: Android <=4.0 only, PhantomJS 1 only + // push.apply(_, arraylike) throws on ancient WebKit + jQuery.merge( scripts, getAll( node, "script" ) ); + } + } + + callback.call( collection[ i ], node, i ); + } + + if ( hasScripts ) { + doc = scripts[ scripts.length - 1 ].ownerDocument; + + // Reenable scripts + jQuery.map( scripts, restoreScript ); + + // Evaluate executable scripts on first document insertion + for ( i = 0; i < hasScripts; i++ ) { + node = scripts[ i ]; + if ( rscriptType.test( node.type || "" ) && + !dataPriv.access( node, "globalEval" ) && + jQuery.contains( doc, node ) ) { + + if ( node.src && ( node.type || "" ).toLowerCase() !== "module" ) { + + // Optional AJAX dependency, but won't run scripts if not present + if ( jQuery._evalUrl && !node.noModule ) { + jQuery._evalUrl( node.src, { + nonce: node.nonce || node.getAttribute( "nonce" ) + }, doc ); + } + } else { + DOMEval( node.textContent.replace( rcleanScript, "" ), node, doc ); + } + } + } + } + } + } + + return collection; +} + +function remove( elem, selector, keepData ) { + var node, + nodes = selector ? jQuery.filter( selector, elem ) : elem, + i = 0; + + for ( ; ( node = nodes[ i ] ) != null; i++ ) { + if ( !keepData && node.nodeType === 1 ) { + jQuery.cleanData( getAll( node ) ); + } + + if ( node.parentNode ) { + if ( keepData && isAttached( node ) ) { + setGlobalEval( getAll( node, "script" ) ); + } + node.parentNode.removeChild( node ); + } + } + + return elem; +} + +jQuery.extend( { + htmlPrefilter: function( html ) { + return html; + }, + + clone: function( elem, dataAndEvents, deepDataAndEvents ) { + var i, l, srcElements, destElements, + clone = elem.cloneNode( true ), + inPage = isAttached( elem ); + + // Fix IE cloning issues + if ( !support.noCloneChecked && ( elem.nodeType === 1 || elem.nodeType === 11 ) && + !jQuery.isXMLDoc( elem ) ) { + + // We eschew Sizzle here for performance reasons: https://jsperf.com/getall-vs-sizzle/2 + destElements = getAll( clone ); + srcElements = getAll( elem ); + + for ( i = 0, l = srcElements.length; i < l; i++ ) { + fixInput( srcElements[ i ], destElements[ i ] ); + } + } + + // Copy the events from the original to the clone + if ( dataAndEvents ) { + if ( deepDataAndEvents ) { + srcElements = srcElements || getAll( elem ); + destElements = destElements || getAll( clone ); + + for ( i = 0, l = srcElements.length; i < l; i++ ) { + cloneCopyEvent( srcElements[ i ], destElements[ i ] ); + } + } else { + cloneCopyEvent( elem, clone ); + } + } + + // Preserve script evaluation history + destElements = getAll( clone, "script" ); + if ( destElements.length > 0 ) { + setGlobalEval( destElements, !inPage && getAll( elem, "script" ) ); + } + + // Return the cloned set + return clone; + }, + + cleanData: function( elems ) { + var data, elem, type, + special = jQuery.event.special, + i = 0; + + for ( ; ( elem = elems[ i ] ) !== undefined; i++ ) { + if ( acceptData( elem ) ) { + if ( ( data = elem[ dataPriv.expando ] ) ) { + if ( data.events ) { + for ( type in data.events ) { + if ( special[ type ] ) { + jQuery.event.remove( elem, type ); + + // This is a shortcut to avoid jQuery.event.remove's overhead + } else { + jQuery.removeEvent( elem, type, data.handle ); + } + } + } + + // Support: Chrome <=35 - 45+ + // Assign undefined instead of using delete, see Data#remove + elem[ dataPriv.expando ] = undefined; + } + if ( elem[ dataUser.expando ] ) { + + // Support: Chrome <=35 - 45+ + // Assign undefined instead of using delete, see Data#remove + elem[ dataUser.expando ] = undefined; + } + } + } + } +} ); + +jQuery.fn.extend( { + detach: function( selector ) { + return remove( this, selector, true ); + }, + + remove: function( selector ) { + return remove( this, selector ); + }, + + text: function( value ) { + return access( this, function( value ) { + return value === undefined ? + jQuery.text( this ) : + this.empty().each( function() { + if ( this.nodeType === 1 || this.nodeType === 11 || this.nodeType === 9 ) { + this.textContent = value; + } + } ); + }, null, value, arguments.length ); + }, + + append: function() { + return domManip( this, arguments, function( elem ) { + if ( this.nodeType === 1 || this.nodeType === 11 || this.nodeType === 9 ) { + var target = manipulationTarget( this, elem ); + target.appendChild( elem ); + } + } ); + }, + + prepend: function() { + return domManip( this, arguments, function( elem ) { + if ( this.nodeType === 1 || this.nodeType === 11 || this.nodeType === 9 ) { + var target = manipulationTarget( this, elem ); + target.insertBefore( elem, target.firstChild ); + } + } ); + }, + + before: function() { + return domManip( this, arguments, function( elem ) { + if ( this.parentNode ) { + this.parentNode.insertBefore( elem, this ); + } + } ); + }, + + after: function() { + return domManip( this, arguments, function( elem ) { + if ( this.parentNode ) { + this.parentNode.insertBefore( elem, this.nextSibling ); + } + } ); + }, + + empty: function() { + var elem, + i = 0; + + for ( ; ( elem = this[ i ] ) != null; i++ ) { + if ( elem.nodeType === 1 ) { + + // Prevent memory leaks + jQuery.cleanData( getAll( elem, false ) ); + + // Remove any remaining nodes + elem.textContent = ""; + } + } + + return this; + }, + + clone: function( dataAndEvents, deepDataAndEvents ) { + dataAndEvents = dataAndEvents == null ? false : dataAndEvents; + deepDataAndEvents = deepDataAndEvents == null ? dataAndEvents : deepDataAndEvents; + + return this.map( function() { + return jQuery.clone( this, dataAndEvents, deepDataAndEvents ); + } ); + }, + + html: function( value ) { + return access( this, function( value ) { + var elem = this[ 0 ] || {}, + i = 0, + l = this.length; + + if ( value === undefined && elem.nodeType === 1 ) { + return elem.innerHTML; + } + + // See if we can take a shortcut and just use innerHTML + if ( typeof value === "string" && !rnoInnerhtml.test( value ) && + !wrapMap[ ( rtagName.exec( value ) || [ "", "" ] )[ 1 ].toLowerCase() ] ) { + + value = jQuery.htmlPrefilter( value ); + + try { + for ( ; i < l; i++ ) { + elem = this[ i ] || {}; + + // Remove element nodes and prevent memory leaks + if ( elem.nodeType === 1 ) { + jQuery.cleanData( getAll( elem, false ) ); + elem.innerHTML = value; + } + } + + elem = 0; + + // If using innerHTML throws an exception, use the fallback method + } catch ( e ) {} + } + + if ( elem ) { + this.empty().append( value ); + } + }, null, value, arguments.length ); + }, + + replaceWith: function() { + var ignored = []; + + // Make the changes, replacing each non-ignored context element with the new content + return domManip( this, arguments, function( elem ) { + var parent = this.parentNode; + + if ( jQuery.inArray( this, ignored ) < 0 ) { + jQuery.cleanData( getAll( this ) ); + if ( parent ) { + parent.replaceChild( elem, this ); + } + } + + // Force callback invocation + }, ignored ); + } +} ); + +jQuery.each( { + appendTo: "append", + prependTo: "prepend", + insertBefore: "before", + insertAfter: "after", + replaceAll: "replaceWith" +}, function( name, original ) { + jQuery.fn[ name ] = function( selector ) { + var elems, + ret = [], + insert = jQuery( selector ), + last = insert.length - 1, + i = 0; + + for ( ; i <= last; i++ ) { + elems = i === last ? this : this.clone( true ); + jQuery( insert[ i ] )[ original ]( elems ); + + // Support: Android <=4.0 only, PhantomJS 1 only + // .get() because push.apply(_, arraylike) throws on ancient WebKit + push.apply( ret, elems.get() ); + } + + return this.pushStack( ret ); + }; +} ); +var rnumnonpx = new RegExp( "^(" + pnum + ")(?!px)[a-z%]+$", "i" ); + +var getStyles = function( elem ) { + + // Support: IE <=11 only, Firefox <=30 (#15098, #14150) + // IE throws on elements created in popups + // FF meanwhile throws on frame elements through "defaultView.getComputedStyle" + var view = elem.ownerDocument.defaultView; + + if ( !view || !view.opener ) { + view = window; + } + + return view.getComputedStyle( elem ); + }; + +var swap = function( elem, options, callback ) { + var ret, name, + old = {}; + + // Remember the old values, and insert the new ones + for ( name in options ) { + old[ name ] = elem.style[ name ]; + elem.style[ name ] = options[ name ]; + } + + ret = callback.call( elem ); + + // Revert the old values + for ( name in options ) { + elem.style[ name ] = old[ name ]; + } + + return ret; +}; + + +var rboxStyle = new RegExp( cssExpand.join( "|" ), "i" ); + + + +( function() { + + // Executing both pixelPosition & boxSizingReliable tests require only one layout + // so they're executed at the same time to save the second computation. + function computeStyleTests() { + + // This is a singleton, we need to execute it only once + if ( !div ) { + return; + } + + container.style.cssText = "position:absolute;left:-11111px;width:60px;" + + "margin-top:1px;padding:0;border:0"; + div.style.cssText = + "position:relative;display:block;box-sizing:border-box;overflow:scroll;" + + "margin:auto;border:1px;padding:1px;" + + "width:60%;top:1%"; + documentElement.appendChild( container ).appendChild( div ); + + var divStyle = window.getComputedStyle( div ); + pixelPositionVal = divStyle.top !== "1%"; + + // Support: Android 4.0 - 4.3 only, Firefox <=3 - 44 + reliableMarginLeftVal = roundPixelMeasures( divStyle.marginLeft ) === 12; + + // Support: Android 4.0 - 4.3 only, Safari <=9.1 - 10.1, iOS <=7.0 - 9.3 + // Some styles come back with percentage values, even though they shouldn't + div.style.right = "60%"; + pixelBoxStylesVal = roundPixelMeasures( divStyle.right ) === 36; + + // Support: IE 9 - 11 only + // Detect misreporting of content dimensions for box-sizing:border-box elements + boxSizingReliableVal = roundPixelMeasures( divStyle.width ) === 36; + + // Support: IE 9 only + // Detect overflow:scroll screwiness (gh-3699) + // Support: Chrome <=64 + // Don't get tricked when zoom affects offsetWidth (gh-4029) + div.style.position = "absolute"; + scrollboxSizeVal = roundPixelMeasures( div.offsetWidth / 3 ) === 12; + + documentElement.removeChild( container ); + + // Nullify the div so it wouldn't be stored in the memory and + // it will also be a sign that checks already performed + div = null; + } + + function roundPixelMeasures( measure ) { + return Math.round( parseFloat( measure ) ); + } + + var pixelPositionVal, boxSizingReliableVal, scrollboxSizeVal, pixelBoxStylesVal, + reliableTrDimensionsVal, reliableMarginLeftVal, + container = document.createElement( "div" ), + div = document.createElement( "div" ); + + // Finish early in limited (non-browser) environments + if ( !div.style ) { + return; + } + + // Support: IE <=9 - 11 only + // Style of cloned element affects source element cloned (#8908) + div.style.backgroundClip = "content-box"; + div.cloneNode( true ).style.backgroundClip = ""; + support.clearCloneStyle = div.style.backgroundClip === "content-box"; + + jQuery.extend( support, { + boxSizingReliable: function() { + computeStyleTests(); + return boxSizingReliableVal; + }, + pixelBoxStyles: function() { + computeStyleTests(); + return pixelBoxStylesVal; + }, + pixelPosition: function() { + computeStyleTests(); + return pixelPositionVal; + }, + reliableMarginLeft: function() { + computeStyleTests(); + return reliableMarginLeftVal; + }, + scrollboxSize: function() { + computeStyleTests(); + return scrollboxSizeVal; + }, + + // Support: IE 9 - 11+, Edge 15 - 18+ + // IE/Edge misreport `getComputedStyle` of table rows with width/height + // set in CSS while `offset*` properties report correct values. + // Behavior in IE 9 is more subtle than in newer versions & it passes + // some versions of this test; make sure not to make it pass there! + // + // Support: Firefox 70+ + // Only Firefox includes border widths + // in computed dimensions. (gh-4529) + reliableTrDimensions: function() { + var table, tr, trChild, trStyle; + if ( reliableTrDimensionsVal == null ) { + table = document.createElement( "table" ); + tr = document.createElement( "tr" ); + trChild = document.createElement( "div" ); + + table.style.cssText = "position:absolute;left:-11111px;border-collapse:separate"; + tr.style.cssText = "border:1px solid"; + + // Support: Chrome 86+ + // Height set through cssText does not get applied. + // Computed height then comes back as 0. + tr.style.height = "1px"; + trChild.style.height = "9px"; + + // Support: Android 8 Chrome 86+ + // In our bodyBackground.html iframe, + // display for all div elements is set to "inline", + // which causes a problem only in Android 8 Chrome 86. + // Ensuring the div is display: block + // gets around this issue. + trChild.style.display = "block"; + + documentElement + .appendChild( table ) + .appendChild( tr ) + .appendChild( trChild ); + + trStyle = window.getComputedStyle( tr ); + reliableTrDimensionsVal = ( parseInt( trStyle.height, 10 ) + + parseInt( trStyle.borderTopWidth, 10 ) + + parseInt( trStyle.borderBottomWidth, 10 ) ) === tr.offsetHeight; + + documentElement.removeChild( table ); + } + return reliableTrDimensionsVal; + } + } ); +} )(); + + +function curCSS( elem, name, computed ) { + var width, minWidth, maxWidth, ret, + + // Support: Firefox 51+ + // Retrieving style before computed somehow + // fixes an issue with getting wrong values + // on detached elements + style = elem.style; + + computed = computed || getStyles( elem ); + + // getPropertyValue is needed for: + // .css('filter') (IE 9 only, #12537) + // .css('--customProperty) (#3144) + if ( computed ) { + ret = computed.getPropertyValue( name ) || computed[ name ]; + + if ( ret === "" && !isAttached( elem ) ) { + ret = jQuery.style( elem, name ); + } + + // A tribute to the "awesome hack by Dean Edwards" + // Android Browser returns percentage for some values, + // but width seems to be reliably pixels. + // This is against the CSSOM draft spec: + // https://drafts.csswg.org/cssom/#resolved-values + if ( !support.pixelBoxStyles() && rnumnonpx.test( ret ) && rboxStyle.test( name ) ) { + + // Remember the original values + width = style.width; + minWidth = style.minWidth; + maxWidth = style.maxWidth; + + // Put in the new values to get a computed value out + style.minWidth = style.maxWidth = style.width = ret; + ret = computed.width; + + // Revert the changed values + style.width = width; + style.minWidth = minWidth; + style.maxWidth = maxWidth; + } + } + + return ret !== undefined ? + + // Support: IE <=9 - 11 only + // IE returns zIndex value as an integer. + ret + "" : + ret; +} + + +function addGetHookIf( conditionFn, hookFn ) { + + // Define the hook, we'll check on the first run if it's really needed. + return { + get: function() { + if ( conditionFn() ) { + + // Hook not needed (or it's not possible to use it due + // to missing dependency), remove it. + delete this.get; + return; + } + + // Hook needed; redefine it so that the support test is not executed again. + return ( this.get = hookFn ).apply( this, arguments ); + } + }; +} + + +var cssPrefixes = [ "Webkit", "Moz", "ms" ], + emptyStyle = document.createElement( "div" ).style, + vendorProps = {}; + +// Return a vendor-prefixed property or undefined +function vendorPropName( name ) { + + // Check for vendor prefixed names + var capName = name[ 0 ].toUpperCase() + name.slice( 1 ), + i = cssPrefixes.length; + + while ( i-- ) { + name = cssPrefixes[ i ] + capName; + if ( name in emptyStyle ) { + return name; + } + } +} + +// Return a potentially-mapped jQuery.cssProps or vendor prefixed property +function finalPropName( name ) { + var final = jQuery.cssProps[ name ] || vendorProps[ name ]; + + if ( final ) { + return final; + } + if ( name in emptyStyle ) { + return name; + } + return vendorProps[ name ] = vendorPropName( name ) || name; +} + + +var + + // Swappable if display is none or starts with table + // except "table", "table-cell", or "table-caption" + // See here for display values: https://developer.mozilla.org/en-US/docs/CSS/display + rdisplayswap = /^(none|table(?!-c[ea]).+)/, + rcustomProp = /^--/, + cssShow = { position: "absolute", visibility: "hidden", display: "block" }, + cssNormalTransform = { + letterSpacing: "0", + fontWeight: "400" + }; + +function setPositiveNumber( _elem, value, subtract ) { + + // Any relative (+/-) values have already been + // normalized at this point + var matches = rcssNum.exec( value ); + return matches ? + + // Guard against undefined "subtract", e.g., when used as in cssHooks + Math.max( 0, matches[ 2 ] - ( subtract || 0 ) ) + ( matches[ 3 ] || "px" ) : + value; +} + +function boxModelAdjustment( elem, dimension, box, isBorderBox, styles, computedVal ) { + var i = dimension === "width" ? 1 : 0, + extra = 0, + delta = 0; + + // Adjustment may not be necessary + if ( box === ( isBorderBox ? "border" : "content" ) ) { + return 0; + } + + for ( ; i < 4; i += 2 ) { + + // Both box models exclude margin + if ( box === "margin" ) { + delta += jQuery.css( elem, box + cssExpand[ i ], true, styles ); + } + + // If we get here with a content-box, we're seeking "padding" or "border" or "margin" + if ( !isBorderBox ) { + + // Add padding + delta += jQuery.css( elem, "padding" + cssExpand[ i ], true, styles ); + + // For "border" or "margin", add border + if ( box !== "padding" ) { + delta += jQuery.css( elem, "border" + cssExpand[ i ] + "Width", true, styles ); + + // But still keep track of it otherwise + } else { + extra += jQuery.css( elem, "border" + cssExpand[ i ] + "Width", true, styles ); + } + + // If we get here with a border-box (content + padding + border), we're seeking "content" or + // "padding" or "margin" + } else { + + // For "content", subtract padding + if ( box === "content" ) { + delta -= jQuery.css( elem, "padding" + cssExpand[ i ], true, styles ); + } + + // For "content" or "padding", subtract border + if ( box !== "margin" ) { + delta -= jQuery.css( elem, "border" + cssExpand[ i ] + "Width", true, styles ); + } + } + } + + // Account for positive content-box scroll gutter when requested by providing computedVal + if ( !isBorderBox && computedVal >= 0 ) { + + // offsetWidth/offsetHeight is a rounded sum of content, padding, scroll gutter, and border + // Assuming integer scroll gutter, subtract the rest and round down + delta += Math.max( 0, Math.ceil( + elem[ "offset" + dimension[ 0 ].toUpperCase() + dimension.slice( 1 ) ] - + computedVal - + delta - + extra - + 0.5 + + // If offsetWidth/offsetHeight is unknown, then we can't determine content-box scroll gutter + // Use an explicit zero to avoid NaN (gh-3964) + ) ) || 0; + } + + return delta; +} + +function getWidthOrHeight( elem, dimension, extra ) { + + // Start with computed style + var styles = getStyles( elem ), + + // To avoid forcing a reflow, only fetch boxSizing if we need it (gh-4322). + // Fake content-box until we know it's needed to know the true value. + boxSizingNeeded = !support.boxSizingReliable() || extra, + isBorderBox = boxSizingNeeded && + jQuery.css( elem, "boxSizing", false, styles ) === "border-box", + valueIsBorderBox = isBorderBox, + + val = curCSS( elem, dimension, styles ), + offsetProp = "offset" + dimension[ 0 ].toUpperCase() + dimension.slice( 1 ); + + // Support: Firefox <=54 + // Return a confounding non-pixel value or feign ignorance, as appropriate. + if ( rnumnonpx.test( val ) ) { + if ( !extra ) { + return val; + } + val = "auto"; + } + + + // Support: IE 9 - 11 only + // Use offsetWidth/offsetHeight for when box sizing is unreliable. + // In those cases, the computed value can be trusted to be border-box. + if ( ( !support.boxSizingReliable() && isBorderBox || + + // Support: IE 10 - 11+, Edge 15 - 18+ + // IE/Edge misreport `getComputedStyle` of table rows with width/height + // set in CSS while `offset*` properties report correct values. + // Interestingly, in some cases IE 9 doesn't suffer from this issue. + !support.reliableTrDimensions() && nodeName( elem, "tr" ) || + + // Fall back to offsetWidth/offsetHeight when value is "auto" + // This happens for inline elements with no explicit setting (gh-3571) + val === "auto" || + + // Support: Android <=4.1 - 4.3 only + // Also use offsetWidth/offsetHeight for misreported inline dimensions (gh-3602) + !parseFloat( val ) && jQuery.css( elem, "display", false, styles ) === "inline" ) && + + // Make sure the element is visible & connected + elem.getClientRects().length ) { + + isBorderBox = jQuery.css( elem, "boxSizing", false, styles ) === "border-box"; + + // Where available, offsetWidth/offsetHeight approximate border box dimensions. + // Where not available (e.g., SVG), assume unreliable box-sizing and interpret the + // retrieved value as a content box dimension. + valueIsBorderBox = offsetProp in elem; + if ( valueIsBorderBox ) { + val = elem[ offsetProp ]; + } + } + + // Normalize "" and auto + val = parseFloat( val ) || 0; + + // Adjust for the element's box model + return ( val + + boxModelAdjustment( + elem, + dimension, + extra || ( isBorderBox ? "border" : "content" ), + valueIsBorderBox, + styles, + + // Provide the current computed size to request scroll gutter calculation (gh-3589) + val + ) + ) + "px"; +} + +jQuery.extend( { + + // Add in style property hooks for overriding the default + // behavior of getting and setting a style property + cssHooks: { + opacity: { + get: function( elem, computed ) { + if ( computed ) { + + // We should always get a number back from opacity + var ret = curCSS( elem, "opacity" ); + return ret === "" ? "1" : ret; + } + } + } + }, + + // Don't automatically add "px" to these possibly-unitless properties + cssNumber: { + "animationIterationCount": true, + "columnCount": true, + "fillOpacity": true, + "flexGrow": true, + "flexShrink": true, + "fontWeight": true, + "gridArea": true, + "gridColumn": true, + "gridColumnEnd": true, + "gridColumnStart": true, + "gridRow": true, + "gridRowEnd": true, + "gridRowStart": true, + "lineHeight": true, + "opacity": true, + "order": true, + "orphans": true, + "widows": true, + "zIndex": true, + "zoom": true + }, + + // Add in properties whose names you wish to fix before + // setting or getting the value + cssProps: {}, + + // Get and set the style property on a DOM Node + style: function( elem, name, value, extra ) { + + // Don't set styles on text and comment nodes + if ( !elem || elem.nodeType === 3 || elem.nodeType === 8 || !elem.style ) { + return; + } + + // Make sure that we're working with the right name + var ret, type, hooks, + origName = camelCase( name ), + isCustomProp = rcustomProp.test( name ), + style = elem.style; + + // Make sure that we're working with the right name. We don't + // want to query the value if it is a CSS custom property + // since they are user-defined. + if ( !isCustomProp ) { + name = finalPropName( origName ); + } + + // Gets hook for the prefixed version, then unprefixed version + hooks = jQuery.cssHooks[ name ] || jQuery.cssHooks[ origName ]; + + // Check if we're setting a value + if ( value !== undefined ) { + type = typeof value; + + // Convert "+=" or "-=" to relative numbers (#7345) + if ( type === "string" && ( ret = rcssNum.exec( value ) ) && ret[ 1 ] ) { + value = adjustCSS( elem, name, ret ); + + // Fixes bug #9237 + type = "number"; + } + + // Make sure that null and NaN values aren't set (#7116) + if ( value == null || value !== value ) { + return; + } + + // If a number was passed in, add the unit (except for certain CSS properties) + // The isCustomProp check can be removed in jQuery 4.0 when we only auto-append + // "px" to a few hardcoded values. + if ( type === "number" && !isCustomProp ) { + value += ret && ret[ 3 ] || ( jQuery.cssNumber[ origName ] ? "" : "px" ); + } + + // background-* props affect original clone's values + if ( !support.clearCloneStyle && value === "" && name.indexOf( "background" ) === 0 ) { + style[ name ] = "inherit"; + } + + // If a hook was provided, use that value, otherwise just set the specified value + if ( !hooks || !( "set" in hooks ) || + ( value = hooks.set( elem, value, extra ) ) !== undefined ) { + + if ( isCustomProp ) { + style.setProperty( name, value ); + } else { + style[ name ] = value; + } + } + + } else { + + // If a hook was provided get the non-computed value from there + if ( hooks && "get" in hooks && + ( ret = hooks.get( elem, false, extra ) ) !== undefined ) { + + return ret; + } + + // Otherwise just get the value from the style object + return style[ name ]; + } + }, + + css: function( elem, name, extra, styles ) { + var val, num, hooks, + origName = camelCase( name ), + isCustomProp = rcustomProp.test( name ); + + // Make sure that we're working with the right name. We don't + // want to modify the value if it is a CSS custom property + // since they are user-defined. + if ( !isCustomProp ) { + name = finalPropName( origName ); + } + + // Try prefixed name followed by the unprefixed name + hooks = jQuery.cssHooks[ name ] || jQuery.cssHooks[ origName ]; + + // If a hook was provided get the computed value from there + if ( hooks && "get" in hooks ) { + val = hooks.get( elem, true, extra ); + } + + // Otherwise, if a way to get the computed value exists, use that + if ( val === undefined ) { + val = curCSS( elem, name, styles ); + } + + // Convert "normal" to computed value + if ( val === "normal" && name in cssNormalTransform ) { + val = cssNormalTransform[ name ]; + } + + // Make numeric if forced or a qualifier was provided and val looks numeric + if ( extra === "" || extra ) { + num = parseFloat( val ); + return extra === true || isFinite( num ) ? num || 0 : val; + } + + return val; + } +} ); + +jQuery.each( [ "height", "width" ], function( _i, dimension ) { + jQuery.cssHooks[ dimension ] = { + get: function( elem, computed, extra ) { + if ( computed ) { + + // Certain elements can have dimension info if we invisibly show them + // but it must have a current display style that would benefit + return rdisplayswap.test( jQuery.css( elem, "display" ) ) && + + // Support: Safari 8+ + // Table columns in Safari have non-zero offsetWidth & zero + // getBoundingClientRect().width unless display is changed. + // Support: IE <=11 only + // Running getBoundingClientRect on a disconnected node + // in IE throws an error. + ( !elem.getClientRects().length || !elem.getBoundingClientRect().width ) ? + swap( elem, cssShow, function() { + return getWidthOrHeight( elem, dimension, extra ); + } ) : + getWidthOrHeight( elem, dimension, extra ); + } + }, + + set: function( elem, value, extra ) { + var matches, + styles = getStyles( elem ), + + // Only read styles.position if the test has a chance to fail + // to avoid forcing a reflow. + scrollboxSizeBuggy = !support.scrollboxSize() && + styles.position === "absolute", + + // To avoid forcing a reflow, only fetch boxSizing if we need it (gh-3991) + boxSizingNeeded = scrollboxSizeBuggy || extra, + isBorderBox = boxSizingNeeded && + jQuery.css( elem, "boxSizing", false, styles ) === "border-box", + subtract = extra ? + boxModelAdjustment( + elem, + dimension, + extra, + isBorderBox, + styles + ) : + 0; + + // Account for unreliable border-box dimensions by comparing offset* to computed and + // faking a content-box to get border and padding (gh-3699) + if ( isBorderBox && scrollboxSizeBuggy ) { + subtract -= Math.ceil( + elem[ "offset" + dimension[ 0 ].toUpperCase() + dimension.slice( 1 ) ] - + parseFloat( styles[ dimension ] ) - + boxModelAdjustment( elem, dimension, "border", false, styles ) - + 0.5 + ); + } + + // Convert to pixels if value adjustment is needed + if ( subtract && ( matches = rcssNum.exec( value ) ) && + ( matches[ 3 ] || "px" ) !== "px" ) { + + elem.style[ dimension ] = value; + value = jQuery.css( elem, dimension ); + } + + return setPositiveNumber( elem, value, subtract ); + } + }; +} ); + +jQuery.cssHooks.marginLeft = addGetHookIf( support.reliableMarginLeft, + function( elem, computed ) { + if ( computed ) { + return ( parseFloat( curCSS( elem, "marginLeft" ) ) || + elem.getBoundingClientRect().left - + swap( elem, { marginLeft: 0 }, function() { + return elem.getBoundingClientRect().left; + } ) + ) + "px"; + } + } +); + +// These hooks are used by animate to expand properties +jQuery.each( { + margin: "", + padding: "", + border: "Width" +}, function( prefix, suffix ) { + jQuery.cssHooks[ prefix + suffix ] = { + expand: function( value ) { + var i = 0, + expanded = {}, + + // Assumes a single number if not a string + parts = typeof value === "string" ? value.split( " " ) : [ value ]; + + for ( ; i < 4; i++ ) { + expanded[ prefix + cssExpand[ i ] + suffix ] = + parts[ i ] || parts[ i - 2 ] || parts[ 0 ]; + } + + return expanded; + } + }; + + if ( prefix !== "margin" ) { + jQuery.cssHooks[ prefix + suffix ].set = setPositiveNumber; + } +} ); + +jQuery.fn.extend( { + css: function( name, value ) { + return access( this, function( elem, name, value ) { + var styles, len, + map = {}, + i = 0; + + if ( Array.isArray( name ) ) { + styles = getStyles( elem ); + len = name.length; + + for ( ; i < len; i++ ) { + map[ name[ i ] ] = jQuery.css( elem, name[ i ], false, styles ); + } + + return map; + } + + return value !== undefined ? + jQuery.style( elem, name, value ) : + jQuery.css( elem, name ); + }, name, value, arguments.length > 1 ); + } +} ); + + +function Tween( elem, options, prop, end, easing ) { + return new Tween.prototype.init( elem, options, prop, end, easing ); +} +jQuery.Tween = Tween; + +Tween.prototype = { + constructor: Tween, + init: function( elem, options, prop, end, easing, unit ) { + this.elem = elem; + this.prop = prop; + this.easing = easing || jQuery.easing._default; + this.options = options; + this.start = this.now = this.cur(); + this.end = end; + this.unit = unit || ( jQuery.cssNumber[ prop ] ? "" : "px" ); + }, + cur: function() { + var hooks = Tween.propHooks[ this.prop ]; + + return hooks && hooks.get ? + hooks.get( this ) : + Tween.propHooks._default.get( this ); + }, + run: function( percent ) { + var eased, + hooks = Tween.propHooks[ this.prop ]; + + if ( this.options.duration ) { + this.pos = eased = jQuery.easing[ this.easing ]( + percent, this.options.duration * percent, 0, 1, this.options.duration + ); + } else { + this.pos = eased = percent; + } + this.now = ( this.end - this.start ) * eased + this.start; + + if ( this.options.step ) { + this.options.step.call( this.elem, this.now, this ); + } + + if ( hooks && hooks.set ) { + hooks.set( this ); + } else { + Tween.propHooks._default.set( this ); + } + return this; + } +}; + +Tween.prototype.init.prototype = Tween.prototype; + +Tween.propHooks = { + _default: { + get: function( tween ) { + var result; + + // Use a property on the element directly when it is not a DOM element, + // or when there is no matching style property that exists. + if ( tween.elem.nodeType !== 1 || + tween.elem[ tween.prop ] != null && tween.elem.style[ tween.prop ] == null ) { + return tween.elem[ tween.prop ]; + } + + // Passing an empty string as a 3rd parameter to .css will automatically + // attempt a parseFloat and fallback to a string if the parse fails. + // Simple values such as "10px" are parsed to Float; + // complex values such as "rotate(1rad)" are returned as-is. + result = jQuery.css( tween.elem, tween.prop, "" ); + + // Empty strings, null, undefined and "auto" are converted to 0. + return !result || result === "auto" ? 0 : result; + }, + set: function( tween ) { + + // Use step hook for back compat. + // Use cssHook if its there. + // Use .style if available and use plain properties where available. + if ( jQuery.fx.step[ tween.prop ] ) { + jQuery.fx.step[ tween.prop ]( tween ); + } else if ( tween.elem.nodeType === 1 && ( + jQuery.cssHooks[ tween.prop ] || + tween.elem.style[ finalPropName( tween.prop ) ] != null ) ) { + jQuery.style( tween.elem, tween.prop, tween.now + tween.unit ); + } else { + tween.elem[ tween.prop ] = tween.now; + } + } + } +}; + +// Support: IE <=9 only +// Panic based approach to setting things on disconnected nodes +Tween.propHooks.scrollTop = Tween.propHooks.scrollLeft = { + set: function( tween ) { + if ( tween.elem.nodeType && tween.elem.parentNode ) { + tween.elem[ tween.prop ] = tween.now; + } + } +}; + +jQuery.easing = { + linear: function( p ) { + return p; + }, + swing: function( p ) { + return 0.5 - Math.cos( p * Math.PI ) / 2; + }, + _default: "swing" +}; + +jQuery.fx = Tween.prototype.init; + +// Back compat <1.8 extension point +jQuery.fx.step = {}; + + + + +var + fxNow, inProgress, + rfxtypes = /^(?:toggle|show|hide)$/, + rrun = /queueHooks$/; + +function schedule() { + if ( inProgress ) { + if ( document.hidden === false && window.requestAnimationFrame ) { + window.requestAnimationFrame( schedule ); + } else { + window.setTimeout( schedule, jQuery.fx.interval ); + } + + jQuery.fx.tick(); + } +} + +// Animations created synchronously will run synchronously +function createFxNow() { + window.setTimeout( function() { + fxNow = undefined; + } ); + return ( fxNow = Date.now() ); +} + +// Generate parameters to create a standard animation +function genFx( type, includeWidth ) { + var which, + i = 0, + attrs = { height: type }; + + // If we include width, step value is 1 to do all cssExpand values, + // otherwise step value is 2 to skip over Left and Right + includeWidth = includeWidth ? 1 : 0; + for ( ; i < 4; i += 2 - includeWidth ) { + which = cssExpand[ i ]; + attrs[ "margin" + which ] = attrs[ "padding" + which ] = type; + } + + if ( includeWidth ) { + attrs.opacity = attrs.width = type; + } + + return attrs; +} + +function createTween( value, prop, animation ) { + var tween, + collection = ( Animation.tweeners[ prop ] || [] ).concat( Animation.tweeners[ "*" ] ), + index = 0, + length = collection.length; + for ( ; index < length; index++ ) { + if ( ( tween = collection[ index ].call( animation, prop, value ) ) ) { + + // We're done with this property + return tween; + } + } +} + +function defaultPrefilter( elem, props, opts ) { + var prop, value, toggle, hooks, oldfire, propTween, restoreDisplay, display, + isBox = "width" in props || "height" in props, + anim = this, + orig = {}, + style = elem.style, + hidden = elem.nodeType && isHiddenWithinTree( elem ), + dataShow = dataPriv.get( elem, "fxshow" ); + + // Queue-skipping animations hijack the fx hooks + if ( !opts.queue ) { + hooks = jQuery._queueHooks( elem, "fx" ); + if ( hooks.unqueued == null ) { + hooks.unqueued = 0; + oldfire = hooks.empty.fire; + hooks.empty.fire = function() { + if ( !hooks.unqueued ) { + oldfire(); + } + }; + } + hooks.unqueued++; + + anim.always( function() { + + // Ensure the complete handler is called before this completes + anim.always( function() { + hooks.unqueued--; + if ( !jQuery.queue( elem, "fx" ).length ) { + hooks.empty.fire(); + } + } ); + } ); + } + + // Detect show/hide animations + for ( prop in props ) { + value = props[ prop ]; + if ( rfxtypes.test( value ) ) { + delete props[ prop ]; + toggle = toggle || value === "toggle"; + if ( value === ( hidden ? "hide" : "show" ) ) { + + // Pretend to be hidden if this is a "show" and + // there is still data from a stopped show/hide + if ( value === "show" && dataShow && dataShow[ prop ] !== undefined ) { + hidden = true; + + // Ignore all other no-op show/hide data + } else { + continue; + } + } + orig[ prop ] = dataShow && dataShow[ prop ] || jQuery.style( elem, prop ); + } + } + + // Bail out if this is a no-op like .hide().hide() + propTween = !jQuery.isEmptyObject( props ); + if ( !propTween && jQuery.isEmptyObject( orig ) ) { + return; + } + + // Restrict "overflow" and "display" styles during box animations + if ( isBox && elem.nodeType === 1 ) { + + // Support: IE <=9 - 11, Edge 12 - 15 + // Record all 3 overflow attributes because IE does not infer the shorthand + // from identically-valued overflowX and overflowY and Edge just mirrors + // the overflowX value there. + opts.overflow = [ style.overflow, style.overflowX, style.overflowY ]; + + // Identify a display type, preferring old show/hide data over the CSS cascade + restoreDisplay = dataShow && dataShow.display; + if ( restoreDisplay == null ) { + restoreDisplay = dataPriv.get( elem, "display" ); + } + display = jQuery.css( elem, "display" ); + if ( display === "none" ) { + if ( restoreDisplay ) { + display = restoreDisplay; + } else { + + // Get nonempty value(s) by temporarily forcing visibility + showHide( [ elem ], true ); + restoreDisplay = elem.style.display || restoreDisplay; + display = jQuery.css( elem, "display" ); + showHide( [ elem ] ); + } + } + + // Animate inline elements as inline-block + if ( display === "inline" || display === "inline-block" && restoreDisplay != null ) { + if ( jQuery.css( elem, "float" ) === "none" ) { + + // Restore the original display value at the end of pure show/hide animations + if ( !propTween ) { + anim.done( function() { + style.display = restoreDisplay; + } ); + if ( restoreDisplay == null ) { + display = style.display; + restoreDisplay = display === "none" ? "" : display; + } + } + style.display = "inline-block"; + } + } + } + + if ( opts.overflow ) { + style.overflow = "hidden"; + anim.always( function() { + style.overflow = opts.overflow[ 0 ]; + style.overflowX = opts.overflow[ 1 ]; + style.overflowY = opts.overflow[ 2 ]; + } ); + } + + // Implement show/hide animations + propTween = false; + for ( prop in orig ) { + + // General show/hide setup for this element animation + if ( !propTween ) { + if ( dataShow ) { + if ( "hidden" in dataShow ) { + hidden = dataShow.hidden; + } + } else { + dataShow = dataPriv.access( elem, "fxshow", { display: restoreDisplay } ); + } + + // Store hidden/visible for toggle so `.stop().toggle()` "reverses" + if ( toggle ) { + dataShow.hidden = !hidden; + } + + // Show elements before animating them + if ( hidden ) { + showHide( [ elem ], true ); + } + + /* eslint-disable no-loop-func */ + + anim.done( function() { + + /* eslint-enable no-loop-func */ + + // The final step of a "hide" animation is actually hiding the element + if ( !hidden ) { + showHide( [ elem ] ); + } + dataPriv.remove( elem, "fxshow" ); + for ( prop in orig ) { + jQuery.style( elem, prop, orig[ prop ] ); + } + } ); + } + + // Per-property setup + propTween = createTween( hidden ? dataShow[ prop ] : 0, prop, anim ); + if ( !( prop in dataShow ) ) { + dataShow[ prop ] = propTween.start; + if ( hidden ) { + propTween.end = propTween.start; + propTween.start = 0; + } + } + } +} + +function propFilter( props, specialEasing ) { + var index, name, easing, value, hooks; + + // camelCase, specialEasing and expand cssHook pass + for ( index in props ) { + name = camelCase( index ); + easing = specialEasing[ name ]; + value = props[ index ]; + if ( Array.isArray( value ) ) { + easing = value[ 1 ]; + value = props[ index ] = value[ 0 ]; + } + + if ( index !== name ) { + props[ name ] = value; + delete props[ index ]; + } + + hooks = jQuery.cssHooks[ name ]; + if ( hooks && "expand" in hooks ) { + value = hooks.expand( value ); + delete props[ name ]; + + // Not quite $.extend, this won't overwrite existing keys. + // Reusing 'index' because we have the correct "name" + for ( index in value ) { + if ( !( index in props ) ) { + props[ index ] = value[ index ]; + specialEasing[ index ] = easing; + } + } + } else { + specialEasing[ name ] = easing; + } + } +} + +function Animation( elem, properties, options ) { + var result, + stopped, + index = 0, + length = Animation.prefilters.length, + deferred = jQuery.Deferred().always( function() { + + // Don't match elem in the :animated selector + delete tick.elem; + } ), + tick = function() { + if ( stopped ) { + return false; + } + var currentTime = fxNow || createFxNow(), + remaining = Math.max( 0, animation.startTime + animation.duration - currentTime ), + + // Support: Android 2.3 only + // Archaic crash bug won't allow us to use `1 - ( 0.5 || 0 )` (#12497) + temp = remaining / animation.duration || 0, + percent = 1 - temp, + index = 0, + length = animation.tweens.length; + + for ( ; index < length; index++ ) { + animation.tweens[ index ].run( percent ); + } + + deferred.notifyWith( elem, [ animation, percent, remaining ] ); + + // If there's more to do, yield + if ( percent < 1 && length ) { + return remaining; + } + + // If this was an empty animation, synthesize a final progress notification + if ( !length ) { + deferred.notifyWith( elem, [ animation, 1, 0 ] ); + } + + // Resolve the animation and report its conclusion + deferred.resolveWith( elem, [ animation ] ); + return false; + }, + animation = deferred.promise( { + elem: elem, + props: jQuery.extend( {}, properties ), + opts: jQuery.extend( true, { + specialEasing: {}, + easing: jQuery.easing._default + }, options ), + originalProperties: properties, + originalOptions: options, + startTime: fxNow || createFxNow(), + duration: options.duration, + tweens: [], + createTween: function( prop, end ) { + var tween = jQuery.Tween( elem, animation.opts, prop, end, + animation.opts.specialEasing[ prop ] || animation.opts.easing ); + animation.tweens.push( tween ); + return tween; + }, + stop: function( gotoEnd ) { + var index = 0, + + // If we are going to the end, we want to run all the tweens + // otherwise we skip this part + length = gotoEnd ? animation.tweens.length : 0; + if ( stopped ) { + return this; + } + stopped = true; + for ( ; index < length; index++ ) { + animation.tweens[ index ].run( 1 ); + } + + // Resolve when we played the last frame; otherwise, reject + if ( gotoEnd ) { + deferred.notifyWith( elem, [ animation, 1, 0 ] ); + deferred.resolveWith( elem, [ animation, gotoEnd ] ); + } else { + deferred.rejectWith( elem, [ animation, gotoEnd ] ); + } + return this; + } + } ), + props = animation.props; + + propFilter( props, animation.opts.specialEasing ); + + for ( ; index < length; index++ ) { + result = Animation.prefilters[ index ].call( animation, elem, props, animation.opts ); + if ( result ) { + if ( isFunction( result.stop ) ) { + jQuery._queueHooks( animation.elem, animation.opts.queue ).stop = + result.stop.bind( result ); + } + return result; + } + } + + jQuery.map( props, createTween, animation ); + + if ( isFunction( animation.opts.start ) ) { + animation.opts.start.call( elem, animation ); + } + + // Attach callbacks from options + animation + .progress( animation.opts.progress ) + .done( animation.opts.done, animation.opts.complete ) + .fail( animation.opts.fail ) + .always( animation.opts.always ); + + jQuery.fx.timer( + jQuery.extend( tick, { + elem: elem, + anim: animation, + queue: animation.opts.queue + } ) + ); + + return animation; +} + +jQuery.Animation = jQuery.extend( Animation, { + + tweeners: { + "*": [ function( prop, value ) { + var tween = this.createTween( prop, value ); + adjustCSS( tween.elem, prop, rcssNum.exec( value ), tween ); + return tween; + } ] + }, + + tweener: function( props, callback ) { + if ( isFunction( props ) ) { + callback = props; + props = [ "*" ]; + } else { + props = props.match( rnothtmlwhite ); + } + + var prop, + index = 0, + length = props.length; + + for ( ; index < length; index++ ) { + prop = props[ index ]; + Animation.tweeners[ prop ] = Animation.tweeners[ prop ] || []; + Animation.tweeners[ prop ].unshift( callback ); + } + }, + + prefilters: [ defaultPrefilter ], + + prefilter: function( callback, prepend ) { + if ( prepend ) { + Animation.prefilters.unshift( callback ); + } else { + Animation.prefilters.push( callback ); + } + } +} ); + +jQuery.speed = function( speed, easing, fn ) { + var opt = speed && typeof speed === "object" ? jQuery.extend( {}, speed ) : { + complete: fn || !fn && easing || + isFunction( speed ) && speed, + duration: speed, + easing: fn && easing || easing && !isFunction( easing ) && easing + }; + + // Go to the end state if fx are off + if ( jQuery.fx.off ) { + opt.duration = 0; + + } else { + if ( typeof opt.duration !== "number" ) { + if ( opt.duration in jQuery.fx.speeds ) { + opt.duration = jQuery.fx.speeds[ opt.duration ]; + + } else { + opt.duration = jQuery.fx.speeds._default; + } + } + } + + // Normalize opt.queue - true/undefined/null -> "fx" + if ( opt.queue == null || opt.queue === true ) { + opt.queue = "fx"; + } + + // Queueing + opt.old = opt.complete; + + opt.complete = function() { + if ( isFunction( opt.old ) ) { + opt.old.call( this ); + } + + if ( opt.queue ) { + jQuery.dequeue( this, opt.queue ); + } + }; + + return opt; +}; + +jQuery.fn.extend( { + fadeTo: function( speed, to, easing, callback ) { + + // Show any hidden elements after setting opacity to 0 + return this.filter( isHiddenWithinTree ).css( "opacity", 0 ).show() + + // Animate to the value specified + .end().animate( { opacity: to }, speed, easing, callback ); + }, + animate: function( prop, speed, easing, callback ) { + var empty = jQuery.isEmptyObject( prop ), + optall = jQuery.speed( speed, easing, callback ), + doAnimation = function() { + + // Operate on a copy of prop so per-property easing won't be lost + var anim = Animation( this, jQuery.extend( {}, prop ), optall ); + + // Empty animations, or finishing resolves immediately + if ( empty || dataPriv.get( this, "finish" ) ) { + anim.stop( true ); + } + }; + + doAnimation.finish = doAnimation; + + return empty || optall.queue === false ? + this.each( doAnimation ) : + this.queue( optall.queue, doAnimation ); + }, + stop: function( type, clearQueue, gotoEnd ) { + var stopQueue = function( hooks ) { + var stop = hooks.stop; + delete hooks.stop; + stop( gotoEnd ); + }; + + if ( typeof type !== "string" ) { + gotoEnd = clearQueue; + clearQueue = type; + type = undefined; + } + if ( clearQueue ) { + this.queue( type || "fx", [] ); + } + + return this.each( function() { + var dequeue = true, + index = type != null && type + "queueHooks", + timers = jQuery.timers, + data = dataPriv.get( this ); + + if ( index ) { + if ( data[ index ] && data[ index ].stop ) { + stopQueue( data[ index ] ); + } + } else { + for ( index in data ) { + if ( data[ index ] && data[ index ].stop && rrun.test( index ) ) { + stopQueue( data[ index ] ); + } + } + } + + for ( index = timers.length; index--; ) { + if ( timers[ index ].elem === this && + ( type == null || timers[ index ].queue === type ) ) { + + timers[ index ].anim.stop( gotoEnd ); + dequeue = false; + timers.splice( index, 1 ); + } + } + + // Start the next in the queue if the last step wasn't forced. + // Timers currently will call their complete callbacks, which + // will dequeue but only if they were gotoEnd. + if ( dequeue || !gotoEnd ) { + jQuery.dequeue( this, type ); + } + } ); + }, + finish: function( type ) { + if ( type !== false ) { + type = type || "fx"; + } + return this.each( function() { + var index, + data = dataPriv.get( this ), + queue = data[ type + "queue" ], + hooks = data[ type + "queueHooks" ], + timers = jQuery.timers, + length = queue ? queue.length : 0; + + // Enable finishing flag on private data + data.finish = true; + + // Empty the queue first + jQuery.queue( this, type, [] ); + + if ( hooks && hooks.stop ) { + hooks.stop.call( this, true ); + } + + // Look for any active animations, and finish them + for ( index = timers.length; index--; ) { + if ( timers[ index ].elem === this && timers[ index ].queue === type ) { + timers[ index ].anim.stop( true ); + timers.splice( index, 1 ); + } + } + + // Look for any animations in the old queue and finish them + for ( index = 0; index < length; index++ ) { + if ( queue[ index ] && queue[ index ].finish ) { + queue[ index ].finish.call( this ); + } + } + + // Turn off finishing flag + delete data.finish; + } ); + } +} ); + +jQuery.each( [ "toggle", "show", "hide" ], function( _i, name ) { + var cssFn = jQuery.fn[ name ]; + jQuery.fn[ name ] = function( speed, easing, callback ) { + return speed == null || typeof speed === "boolean" ? + cssFn.apply( this, arguments ) : + this.animate( genFx( name, true ), speed, easing, callback ); + }; +} ); + +// Generate shortcuts for custom animations +jQuery.each( { + slideDown: genFx( "show" ), + slideUp: genFx( "hide" ), + slideToggle: genFx( "toggle" ), + fadeIn: { opacity: "show" }, + fadeOut: { opacity: "hide" }, + fadeToggle: { opacity: "toggle" } +}, function( name, props ) { + jQuery.fn[ name ] = function( speed, easing, callback ) { + return this.animate( props, speed, easing, callback ); + }; +} ); + +jQuery.timers = []; +jQuery.fx.tick = function() { + var timer, + i = 0, + timers = jQuery.timers; + + fxNow = Date.now(); + + for ( ; i < timers.length; i++ ) { + timer = timers[ i ]; + + // Run the timer and safely remove it when done (allowing for external removal) + if ( !timer() && timers[ i ] === timer ) { + timers.splice( i--, 1 ); + } + } + + if ( !timers.length ) { + jQuery.fx.stop(); + } + fxNow = undefined; +}; + +jQuery.fx.timer = function( timer ) { + jQuery.timers.push( timer ); + jQuery.fx.start(); +}; + +jQuery.fx.interval = 13; +jQuery.fx.start = function() { + if ( inProgress ) { + return; + } + + inProgress = true; + schedule(); +}; + +jQuery.fx.stop = function() { + inProgress = null; +}; + +jQuery.fx.speeds = { + slow: 600, + fast: 200, + + // Default speed + _default: 400 +}; + + +// Based off of the plugin by Clint Helfers, with permission. +// https://web.archive.org/web/20100324014747/http://blindsignals.com/index.php/2009/07/jquery-delay/ +jQuery.fn.delay = function( time, type ) { + time = jQuery.fx ? jQuery.fx.speeds[ time ] || time : time; + type = type || "fx"; + + return this.queue( type, function( next, hooks ) { + var timeout = window.setTimeout( next, time ); + hooks.stop = function() { + window.clearTimeout( timeout ); + }; + } ); +}; + + +( function() { + var input = document.createElement( "input" ), + select = document.createElement( "select" ), + opt = select.appendChild( document.createElement( "option" ) ); + + input.type = "checkbox"; + + // Support: Android <=4.3 only + // Default value for a checkbox should be "on" + support.checkOn = input.value !== ""; + + // Support: IE <=11 only + // Must access selectedIndex to make default options select + support.optSelected = opt.selected; + + // Support: IE <=11 only + // An input loses its value after becoming a radio + input = document.createElement( "input" ); + input.value = "t"; + input.type = "radio"; + support.radioValue = input.value === "t"; +} )(); + + +var boolHook, + attrHandle = jQuery.expr.attrHandle; + +jQuery.fn.extend( { + attr: function( name, value ) { + return access( this, jQuery.attr, name, value, arguments.length > 1 ); + }, + + removeAttr: function( name ) { + return this.each( function() { + jQuery.removeAttr( this, name ); + } ); + } +} ); + +jQuery.extend( { + attr: function( elem, name, value ) { + var ret, hooks, + nType = elem.nodeType; + + // Don't get/set attributes on text, comment and attribute nodes + if ( nType === 3 || nType === 8 || nType === 2 ) { + return; + } + + // Fallback to prop when attributes are not supported + if ( typeof elem.getAttribute === "undefined" ) { + return jQuery.prop( elem, name, value ); + } + + // Attribute hooks are determined by the lowercase version + // Grab necessary hook if one is defined + if ( nType !== 1 || !jQuery.isXMLDoc( elem ) ) { + hooks = jQuery.attrHooks[ name.toLowerCase() ] || + ( jQuery.expr.match.bool.test( name ) ? boolHook : undefined ); + } + + if ( value !== undefined ) { + if ( value === null ) { + jQuery.removeAttr( elem, name ); + return; + } + + if ( hooks && "set" in hooks && + ( ret = hooks.set( elem, value, name ) ) !== undefined ) { + return ret; + } + + elem.setAttribute( name, value + "" ); + return value; + } + + if ( hooks && "get" in hooks && ( ret = hooks.get( elem, name ) ) !== null ) { + return ret; + } + + ret = jQuery.find.attr( elem, name ); + + // Non-existent attributes return null, we normalize to undefined + return ret == null ? undefined : ret; + }, + + attrHooks: { + type: { + set: function( elem, value ) { + if ( !support.radioValue && value === "radio" && + nodeName( elem, "input" ) ) { + var val = elem.value; + elem.setAttribute( "type", value ); + if ( val ) { + elem.value = val; + } + return value; + } + } + } + }, + + removeAttr: function( elem, value ) { + var name, + i = 0, + + // Attribute names can contain non-HTML whitespace characters + // https://html.spec.whatwg.org/multipage/syntax.html#attributes-2 + attrNames = value && value.match( rnothtmlwhite ); + + if ( attrNames && elem.nodeType === 1 ) { + while ( ( name = attrNames[ i++ ] ) ) { + elem.removeAttribute( name ); + } + } + } +} ); + +// Hooks for boolean attributes +boolHook = { + set: function( elem, value, name ) { + if ( value === false ) { + + // Remove boolean attributes when set to false + jQuery.removeAttr( elem, name ); + } else { + elem.setAttribute( name, name ); + } + return name; + } +}; + +jQuery.each( jQuery.expr.match.bool.source.match( /\w+/g ), function( _i, name ) { + var getter = attrHandle[ name ] || jQuery.find.attr; + + attrHandle[ name ] = function( elem, name, isXML ) { + var ret, handle, + lowercaseName = name.toLowerCase(); + + if ( !isXML ) { + + // Avoid an infinite loop by temporarily removing this function from the getter + handle = attrHandle[ lowercaseName ]; + attrHandle[ lowercaseName ] = ret; + ret = getter( elem, name, isXML ) != null ? + lowercaseName : + null; + attrHandle[ lowercaseName ] = handle; + } + return ret; + }; +} ); + + + + +var rfocusable = /^(?:input|select|textarea|button)$/i, + rclickable = /^(?:a|area)$/i; + +jQuery.fn.extend( { + prop: function( name, value ) { + return access( this, jQuery.prop, name, value, arguments.length > 1 ); + }, + + removeProp: function( name ) { + return this.each( function() { + delete this[ jQuery.propFix[ name ] || name ]; + } ); + } +} ); + +jQuery.extend( { + prop: function( elem, name, value ) { + var ret, hooks, + nType = elem.nodeType; + + // Don't get/set properties on text, comment and attribute nodes + if ( nType === 3 || nType === 8 || nType === 2 ) { + return; + } + + if ( nType !== 1 || !jQuery.isXMLDoc( elem ) ) { + + // Fix name and attach hooks + name = jQuery.propFix[ name ] || name; + hooks = jQuery.propHooks[ name ]; + } + + if ( value !== undefined ) { + if ( hooks && "set" in hooks && + ( ret = hooks.set( elem, value, name ) ) !== undefined ) { + return ret; + } + + return ( elem[ name ] = value ); + } + + if ( hooks && "get" in hooks && ( ret = hooks.get( elem, name ) ) !== null ) { + return ret; + } + + return elem[ name ]; + }, + + propHooks: { + tabIndex: { + get: function( elem ) { + + // Support: IE <=9 - 11 only + // elem.tabIndex doesn't always return the + // correct value when it hasn't been explicitly set + // https://web.archive.org/web/20141116233347/http://fluidproject.org/blog/2008/01/09/getting-setting-and-removing-tabindex-values-with-javascript/ + // Use proper attribute retrieval(#12072) + var tabindex = jQuery.find.attr( elem, "tabindex" ); + + if ( tabindex ) { + return parseInt( tabindex, 10 ); + } + + if ( + rfocusable.test( elem.nodeName ) || + rclickable.test( elem.nodeName ) && + elem.href + ) { + return 0; + } + + return -1; + } + } + }, + + propFix: { + "for": "htmlFor", + "class": "className" + } +} ); + +// Support: IE <=11 only +// Accessing the selectedIndex property +// forces the browser to respect setting selected +// on the option +// The getter ensures a default option is selected +// when in an optgroup +// eslint rule "no-unused-expressions" is disabled for this code +// since it considers such accessions noop +if ( !support.optSelected ) { + jQuery.propHooks.selected = { + get: function( elem ) { + + /* eslint no-unused-expressions: "off" */ + + var parent = elem.parentNode; + if ( parent && parent.parentNode ) { + parent.parentNode.selectedIndex; + } + return null; + }, + set: function( elem ) { + + /* eslint no-unused-expressions: "off" */ + + var parent = elem.parentNode; + if ( parent ) { + parent.selectedIndex; + + if ( parent.parentNode ) { + parent.parentNode.selectedIndex; + } + } + } + }; +} + +jQuery.each( [ + "tabIndex", + "readOnly", + "maxLength", + "cellSpacing", + "cellPadding", + "rowSpan", + "colSpan", + "useMap", + "frameBorder", + "contentEditable" +], function() { + jQuery.propFix[ this.toLowerCase() ] = this; +} ); + + + + + // Strip and collapse whitespace according to HTML spec + // https://infra.spec.whatwg.org/#strip-and-collapse-ascii-whitespace + function stripAndCollapse( value ) { + var tokens = value.match( rnothtmlwhite ) || []; + return tokens.join( " " ); + } + + +function getClass( elem ) { + return elem.getAttribute && elem.getAttribute( "class" ) || ""; +} + +function classesToArray( value ) { + if ( Array.isArray( value ) ) { + return value; + } + if ( typeof value === "string" ) { + return value.match( rnothtmlwhite ) || []; + } + return []; +} + +jQuery.fn.extend( { + addClass: function( value ) { + var classes, elem, cur, curValue, clazz, j, finalValue, + i = 0; + + if ( isFunction( value ) ) { + return this.each( function( j ) { + jQuery( this ).addClass( value.call( this, j, getClass( this ) ) ); + } ); + } + + classes = classesToArray( value ); + + if ( classes.length ) { + while ( ( elem = this[ i++ ] ) ) { + curValue = getClass( elem ); + cur = elem.nodeType === 1 && ( " " + stripAndCollapse( curValue ) + " " ); + + if ( cur ) { + j = 0; + while ( ( clazz = classes[ j++ ] ) ) { + if ( cur.indexOf( " " + clazz + " " ) < 0 ) { + cur += clazz + " "; + } + } + + // Only assign if different to avoid unneeded rendering. + finalValue = stripAndCollapse( cur ); + if ( curValue !== finalValue ) { + elem.setAttribute( "class", finalValue ); + } + } + } + } + + return this; + }, + + removeClass: function( value ) { + var classes, elem, cur, curValue, clazz, j, finalValue, + i = 0; + + if ( isFunction( value ) ) { + return this.each( function( j ) { + jQuery( this ).removeClass( value.call( this, j, getClass( this ) ) ); + } ); + } + + if ( !arguments.length ) { + return this.attr( "class", "" ); + } + + classes = classesToArray( value ); + + if ( classes.length ) { + while ( ( elem = this[ i++ ] ) ) { + curValue = getClass( elem ); + + // This expression is here for better compressibility (see addClass) + cur = elem.nodeType === 1 && ( " " + stripAndCollapse( curValue ) + " " ); + + if ( cur ) { + j = 0; + while ( ( clazz = classes[ j++ ] ) ) { + + // Remove *all* instances + while ( cur.indexOf( " " + clazz + " " ) > -1 ) { + cur = cur.replace( " " + clazz + " ", " " ); + } + } + + // Only assign if different to avoid unneeded rendering. + finalValue = stripAndCollapse( cur ); + if ( curValue !== finalValue ) { + elem.setAttribute( "class", finalValue ); + } + } + } + } + + return this; + }, + + toggleClass: function( value, stateVal ) { + var type = typeof value, + isValidValue = type === "string" || Array.isArray( value ); + + if ( typeof stateVal === "boolean" && isValidValue ) { + return stateVal ? this.addClass( value ) : this.removeClass( value ); + } + + if ( isFunction( value ) ) { + return this.each( function( i ) { + jQuery( this ).toggleClass( + value.call( this, i, getClass( this ), stateVal ), + stateVal + ); + } ); + } + + return this.each( function() { + var className, i, self, classNames; + + if ( isValidValue ) { + + // Toggle individual class names + i = 0; + self = jQuery( this ); + classNames = classesToArray( value ); + + while ( ( className = classNames[ i++ ] ) ) { + + // Check each className given, space separated list + if ( self.hasClass( className ) ) { + self.removeClass( className ); + } else { + self.addClass( className ); + } + } + + // Toggle whole class name + } else if ( value === undefined || type === "boolean" ) { + className = getClass( this ); + if ( className ) { + + // Store className if set + dataPriv.set( this, "__className__", className ); + } + + // If the element has a class name or if we're passed `false`, + // then remove the whole classname (if there was one, the above saved it). + // Otherwise bring back whatever was previously saved (if anything), + // falling back to the empty string if nothing was stored. + if ( this.setAttribute ) { + this.setAttribute( "class", + className || value === false ? + "" : + dataPriv.get( this, "__className__" ) || "" + ); + } + } + } ); + }, + + hasClass: function( selector ) { + var className, elem, + i = 0; + + className = " " + selector + " "; + while ( ( elem = this[ i++ ] ) ) { + if ( elem.nodeType === 1 && + ( " " + stripAndCollapse( getClass( elem ) ) + " " ).indexOf( className ) > -1 ) { + return true; + } + } + + return false; + } +} ); + + + + +var rreturn = /\r/g; + +jQuery.fn.extend( { + val: function( value ) { + var hooks, ret, valueIsFunction, + elem = this[ 0 ]; + + if ( !arguments.length ) { + if ( elem ) { + hooks = jQuery.valHooks[ elem.type ] || + jQuery.valHooks[ elem.nodeName.toLowerCase() ]; + + if ( hooks && + "get" in hooks && + ( ret = hooks.get( elem, "value" ) ) !== undefined + ) { + return ret; + } + + ret = elem.value; + + // Handle most common string cases + if ( typeof ret === "string" ) { + return ret.replace( rreturn, "" ); + } + + // Handle cases where value is null/undef or number + return ret == null ? "" : ret; + } + + return; + } + + valueIsFunction = isFunction( value ); + + return this.each( function( i ) { + var val; + + if ( this.nodeType !== 1 ) { + return; + } + + if ( valueIsFunction ) { + val = value.call( this, i, jQuery( this ).val() ); + } else { + val = value; + } + + // Treat null/undefined as ""; convert numbers to string + if ( val == null ) { + val = ""; + + } else if ( typeof val === "number" ) { + val += ""; + + } else if ( Array.isArray( val ) ) { + val = jQuery.map( val, function( value ) { + return value == null ? "" : value + ""; + } ); + } + + hooks = jQuery.valHooks[ this.type ] || jQuery.valHooks[ this.nodeName.toLowerCase() ]; + + // If set returns undefined, fall back to normal setting + if ( !hooks || !( "set" in hooks ) || hooks.set( this, val, "value" ) === undefined ) { + this.value = val; + } + } ); + } +} ); + +jQuery.extend( { + valHooks: { + option: { + get: function( elem ) { + + var val = jQuery.find.attr( elem, "value" ); + return val != null ? + val : + + // Support: IE <=10 - 11 only + // option.text throws exceptions (#14686, #14858) + // Strip and collapse whitespace + // https://html.spec.whatwg.org/#strip-and-collapse-whitespace + stripAndCollapse( jQuery.text( elem ) ); + } + }, + select: { + get: function( elem ) { + var value, option, i, + options = elem.options, + index = elem.selectedIndex, + one = elem.type === "select-one", + values = one ? null : [], + max = one ? index + 1 : options.length; + + if ( index < 0 ) { + i = max; + + } else { + i = one ? index : 0; + } + + // Loop through all the selected options + for ( ; i < max; i++ ) { + option = options[ i ]; + + // Support: IE <=9 only + // IE8-9 doesn't update selected after form reset (#2551) + if ( ( option.selected || i === index ) && + + // Don't return options that are disabled or in a disabled optgroup + !option.disabled && + ( !option.parentNode.disabled || + !nodeName( option.parentNode, "optgroup" ) ) ) { + + // Get the specific value for the option + value = jQuery( option ).val(); + + // We don't need an array for one selects + if ( one ) { + return value; + } + + // Multi-Selects return an array + values.push( value ); + } + } + + return values; + }, + + set: function( elem, value ) { + var optionSet, option, + options = elem.options, + values = jQuery.makeArray( value ), + i = options.length; + + while ( i-- ) { + option = options[ i ]; + + /* eslint-disable no-cond-assign */ + + if ( option.selected = + jQuery.inArray( jQuery.valHooks.option.get( option ), values ) > -1 + ) { + optionSet = true; + } + + /* eslint-enable no-cond-assign */ + } + + // Force browsers to behave consistently when non-matching value is set + if ( !optionSet ) { + elem.selectedIndex = -1; + } + return values; + } + } + } +} ); + +// Radios and checkboxes getter/setter +jQuery.each( [ "radio", "checkbox" ], function() { + jQuery.valHooks[ this ] = { + set: function( elem, value ) { + if ( Array.isArray( value ) ) { + return ( elem.checked = jQuery.inArray( jQuery( elem ).val(), value ) > -1 ); + } + } + }; + if ( !support.checkOn ) { + jQuery.valHooks[ this ].get = function( elem ) { + return elem.getAttribute( "value" ) === null ? "on" : elem.value; + }; + } +} ); + + + + +// Return jQuery for attributes-only inclusion + + +support.focusin = "onfocusin" in window; + + +var rfocusMorph = /^(?:focusinfocus|focusoutblur)$/, + stopPropagationCallback = function( e ) { + e.stopPropagation(); + }; + +jQuery.extend( jQuery.event, { + + trigger: function( event, data, elem, onlyHandlers ) { + + var i, cur, tmp, bubbleType, ontype, handle, special, lastElement, + eventPath = [ elem || document ], + type = hasOwn.call( event, "type" ) ? event.type : event, + namespaces = hasOwn.call( event, "namespace" ) ? event.namespace.split( "." ) : []; + + cur = lastElement = tmp = elem = elem || document; + + // Don't do events on text and comment nodes + if ( elem.nodeType === 3 || elem.nodeType === 8 ) { + return; + } + + // focus/blur morphs to focusin/out; ensure we're not firing them right now + if ( rfocusMorph.test( type + jQuery.event.triggered ) ) { + return; + } + + if ( type.indexOf( "." ) > -1 ) { + + // Namespaced trigger; create a regexp to match event type in handle() + namespaces = type.split( "." ); + type = namespaces.shift(); + namespaces.sort(); + } + ontype = type.indexOf( ":" ) < 0 && "on" + type; + + // Caller can pass in a jQuery.Event object, Object, or just an event type string + event = event[ jQuery.expando ] ? + event : + new jQuery.Event( type, typeof event === "object" && event ); + + // Trigger bitmask: & 1 for native handlers; & 2 for jQuery (always true) + event.isTrigger = onlyHandlers ? 2 : 3; + event.namespace = namespaces.join( "." ); + event.rnamespace = event.namespace ? + new RegExp( "(^|\\.)" + namespaces.join( "\\.(?:.*\\.|)" ) + "(\\.|$)" ) : + null; + + // Clean up the event in case it is being reused + event.result = undefined; + if ( !event.target ) { + event.target = elem; + } + + // Clone any incoming data and prepend the event, creating the handler arg list + data = data == null ? + [ event ] : + jQuery.makeArray( data, [ event ] ); + + // Allow special events to draw outside the lines + special = jQuery.event.special[ type ] || {}; + if ( !onlyHandlers && special.trigger && special.trigger.apply( elem, data ) === false ) { + return; + } + + // Determine event propagation path in advance, per W3C events spec (#9951) + // Bubble up to document, then to window; watch for a global ownerDocument var (#9724) + if ( !onlyHandlers && !special.noBubble && !isWindow( elem ) ) { + + bubbleType = special.delegateType || type; + if ( !rfocusMorph.test( bubbleType + type ) ) { + cur = cur.parentNode; + } + for ( ; cur; cur = cur.parentNode ) { + eventPath.push( cur ); + tmp = cur; + } + + // Only add window if we got to document (e.g., not plain obj or detached DOM) + if ( tmp === ( elem.ownerDocument || document ) ) { + eventPath.push( tmp.defaultView || tmp.parentWindow || window ); + } + } + + // Fire handlers on the event path + i = 0; + while ( ( cur = eventPath[ i++ ] ) && !event.isPropagationStopped() ) { + lastElement = cur; + event.type = i > 1 ? + bubbleType : + special.bindType || type; + + // jQuery handler + handle = ( dataPriv.get( cur, "events" ) || Object.create( null ) )[ event.type ] && + dataPriv.get( cur, "handle" ); + if ( handle ) { + handle.apply( cur, data ); + } + + // Native handler + handle = ontype && cur[ ontype ]; + if ( handle && handle.apply && acceptData( cur ) ) { + event.result = handle.apply( cur, data ); + if ( event.result === false ) { + event.preventDefault(); + } + } + } + event.type = type; + + // If nobody prevented the default action, do it now + if ( !onlyHandlers && !event.isDefaultPrevented() ) { + + if ( ( !special._default || + special._default.apply( eventPath.pop(), data ) === false ) && + acceptData( elem ) ) { + + // Call a native DOM method on the target with the same name as the event. + // Don't do default actions on window, that's where global variables be (#6170) + if ( ontype && isFunction( elem[ type ] ) && !isWindow( elem ) ) { + + // Don't re-trigger an onFOO event when we call its FOO() method + tmp = elem[ ontype ]; + + if ( tmp ) { + elem[ ontype ] = null; + } + + // Prevent re-triggering of the same event, since we already bubbled it above + jQuery.event.triggered = type; + + if ( event.isPropagationStopped() ) { + lastElement.addEventListener( type, stopPropagationCallback ); + } + + elem[ type ](); + + if ( event.isPropagationStopped() ) { + lastElement.removeEventListener( type, stopPropagationCallback ); + } + + jQuery.event.triggered = undefined; + + if ( tmp ) { + elem[ ontype ] = tmp; + } + } + } + } + + return event.result; + }, + + // Piggyback on a donor event to simulate a different one + // Used only for `focus(in | out)` events + simulate: function( type, elem, event ) { + var e = jQuery.extend( + new jQuery.Event(), + event, + { + type: type, + isSimulated: true + } + ); + + jQuery.event.trigger( e, null, elem ); + } + +} ); + +jQuery.fn.extend( { + + trigger: function( type, data ) { + return this.each( function() { + jQuery.event.trigger( type, data, this ); + } ); + }, + triggerHandler: function( type, data ) { + var elem = this[ 0 ]; + if ( elem ) { + return jQuery.event.trigger( type, data, elem, true ); + } + } +} ); + + +// Support: Firefox <=44 +// Firefox doesn't have focus(in | out) events +// Related ticket - https://bugzilla.mozilla.org/show_bug.cgi?id=687787 +// +// Support: Chrome <=48 - 49, Safari <=9.0 - 9.1 +// focus(in | out) events fire after focus & blur events, +// which is spec violation - http://www.w3.org/TR/DOM-Level-3-Events/#events-focusevent-event-order +// Related ticket - https://bugs.chromium.org/p/chromium/issues/detail?id=449857 +if ( !support.focusin ) { + jQuery.each( { focus: "focusin", blur: "focusout" }, function( orig, fix ) { + + // Attach a single capturing handler on the document while someone wants focusin/focusout + var handler = function( event ) { + jQuery.event.simulate( fix, event.target, jQuery.event.fix( event ) ); + }; + + jQuery.event.special[ fix ] = { + setup: function() { + + // Handle: regular nodes (via `this.ownerDocument`), window + // (via `this.document`) & document (via `this`). + var doc = this.ownerDocument || this.document || this, + attaches = dataPriv.access( doc, fix ); + + if ( !attaches ) { + doc.addEventListener( orig, handler, true ); + } + dataPriv.access( doc, fix, ( attaches || 0 ) + 1 ); + }, + teardown: function() { + var doc = this.ownerDocument || this.document || this, + attaches = dataPriv.access( doc, fix ) - 1; + + if ( !attaches ) { + doc.removeEventListener( orig, handler, true ); + dataPriv.remove( doc, fix ); + + } else { + dataPriv.access( doc, fix, attaches ); + } + } + }; + } ); +} +var location = window.location; + +var nonce = { guid: Date.now() }; + +var rquery = ( /\?/ ); + + + +// Cross-browser xml parsing +jQuery.parseXML = function( data ) { + var xml, parserErrorElem; + if ( !data || typeof data !== "string" ) { + return null; + } + + // Support: IE 9 - 11 only + // IE throws on parseFromString with invalid input. + try { + xml = ( new window.DOMParser() ).parseFromString( data, "text/xml" ); + } catch ( e ) {} + + parserErrorElem = xml && xml.getElementsByTagName( "parsererror" )[ 0 ]; + if ( !xml || parserErrorElem ) { + jQuery.error( "Invalid XML: " + ( + parserErrorElem ? + jQuery.map( parserErrorElem.childNodes, function( el ) { + return el.textContent; + } ).join( "\n" ) : + data + ) ); + } + return xml; +}; + + +var + rbracket = /\[\]$/, + rCRLF = /\r?\n/g, + rsubmitterTypes = /^(?:submit|button|image|reset|file)$/i, + rsubmittable = /^(?:input|select|textarea|keygen)/i; + +function buildParams( prefix, obj, traditional, add ) { + var name; + + if ( Array.isArray( obj ) ) { + + // Serialize array item. + jQuery.each( obj, function( i, v ) { + if ( traditional || rbracket.test( prefix ) ) { + + // Treat each array item as a scalar. + add( prefix, v ); + + } else { + + // Item is non-scalar (array or object), encode its numeric index. + buildParams( + prefix + "[" + ( typeof v === "object" && v != null ? i : "" ) + "]", + v, + traditional, + add + ); + } + } ); + + } else if ( !traditional && toType( obj ) === "object" ) { + + // Serialize object item. + for ( name in obj ) { + buildParams( prefix + "[" + name + "]", obj[ name ], traditional, add ); + } + + } else { + + // Serialize scalar item. + add( prefix, obj ); + } +} + +// Serialize an array of form elements or a set of +// key/values into a query string +jQuery.param = function( a, traditional ) { + var prefix, + s = [], + add = function( key, valueOrFunction ) { + + // If value is a function, invoke it and use its return value + var value = isFunction( valueOrFunction ) ? + valueOrFunction() : + valueOrFunction; + + s[ s.length ] = encodeURIComponent( key ) + "=" + + encodeURIComponent( value == null ? "" : value ); + }; + + if ( a == null ) { + return ""; + } + + // If an array was passed in, assume that it is an array of form elements. + if ( Array.isArray( a ) || ( a.jquery && !jQuery.isPlainObject( a ) ) ) { + + // Serialize the form elements + jQuery.each( a, function() { + add( this.name, this.value ); + } ); + + } else { + + // If traditional, encode the "old" way (the way 1.3.2 or older + // did it), otherwise encode params recursively. + for ( prefix in a ) { + buildParams( prefix, a[ prefix ], traditional, add ); + } + } + + // Return the resulting serialization + return s.join( "&" ); +}; + +jQuery.fn.extend( { + serialize: function() { + return jQuery.param( this.serializeArray() ); + }, + serializeArray: function() { + return this.map( function() { + + // Can add propHook for "elements" to filter or add form elements + var elements = jQuery.prop( this, "elements" ); + return elements ? jQuery.makeArray( elements ) : this; + } ).filter( function() { + var type = this.type; + + // Use .is( ":disabled" ) so that fieldset[disabled] works + return this.name && !jQuery( this ).is( ":disabled" ) && + rsubmittable.test( this.nodeName ) && !rsubmitterTypes.test( type ) && + ( this.checked || !rcheckableType.test( type ) ); + } ).map( function( _i, elem ) { + var val = jQuery( this ).val(); + + if ( val == null ) { + return null; + } + + if ( Array.isArray( val ) ) { + return jQuery.map( val, function( val ) { + return { name: elem.name, value: val.replace( rCRLF, "\r\n" ) }; + } ); + } + + return { name: elem.name, value: val.replace( rCRLF, "\r\n" ) }; + } ).get(); + } +} ); + + +var + r20 = /%20/g, + rhash = /#.*$/, + rantiCache = /([?&])_=[^&]*/, + rheaders = /^(.*?):[ \t]*([^\r\n]*)$/mg, + + // #7653, #8125, #8152: local protocol detection + rlocalProtocol = /^(?:about|app|app-storage|.+-extension|file|res|widget):$/, + rnoContent = /^(?:GET|HEAD)$/, + rprotocol = /^\/\//, + + /* Prefilters + * 1) They are useful to introduce custom dataTypes (see ajax/jsonp.js for an example) + * 2) These are called: + * - BEFORE asking for a transport + * - AFTER param serialization (s.data is a string if s.processData is true) + * 3) key is the dataType + * 4) the catchall symbol "*" can be used + * 5) execution will start with transport dataType and THEN continue down to "*" if needed + */ + prefilters = {}, + + /* Transports bindings + * 1) key is the dataType + * 2) the catchall symbol "*" can be used + * 3) selection will start with transport dataType and THEN go to "*" if needed + */ + transports = {}, + + // Avoid comment-prolog char sequence (#10098); must appease lint and evade compression + allTypes = "*/".concat( "*" ), + + // Anchor tag for parsing the document origin + originAnchor = document.createElement( "a" ); + +originAnchor.href = location.href; + +// Base "constructor" for jQuery.ajaxPrefilter and jQuery.ajaxTransport +function addToPrefiltersOrTransports( structure ) { + + // dataTypeExpression is optional and defaults to "*" + return function( dataTypeExpression, func ) { + + if ( typeof dataTypeExpression !== "string" ) { + func = dataTypeExpression; + dataTypeExpression = "*"; + } + + var dataType, + i = 0, + dataTypes = dataTypeExpression.toLowerCase().match( rnothtmlwhite ) || []; + + if ( isFunction( func ) ) { + + // For each dataType in the dataTypeExpression + while ( ( dataType = dataTypes[ i++ ] ) ) { + + // Prepend if requested + if ( dataType[ 0 ] === "+" ) { + dataType = dataType.slice( 1 ) || "*"; + ( structure[ dataType ] = structure[ dataType ] || [] ).unshift( func ); + + // Otherwise append + } else { + ( structure[ dataType ] = structure[ dataType ] || [] ).push( func ); + } + } + } + }; +} + +// Base inspection function for prefilters and transports +function inspectPrefiltersOrTransports( structure, options, originalOptions, jqXHR ) { + + var inspected = {}, + seekingTransport = ( structure === transports ); + + function inspect( dataType ) { + var selected; + inspected[ dataType ] = true; + jQuery.each( structure[ dataType ] || [], function( _, prefilterOrFactory ) { + var dataTypeOrTransport = prefilterOrFactory( options, originalOptions, jqXHR ); + if ( typeof dataTypeOrTransport === "string" && + !seekingTransport && !inspected[ dataTypeOrTransport ] ) { + + options.dataTypes.unshift( dataTypeOrTransport ); + inspect( dataTypeOrTransport ); + return false; + } else if ( seekingTransport ) { + return !( selected = dataTypeOrTransport ); + } + } ); + return selected; + } + + return inspect( options.dataTypes[ 0 ] ) || !inspected[ "*" ] && inspect( "*" ); +} + +// A special extend for ajax options +// that takes "flat" options (not to be deep extended) +// Fixes #9887 +function ajaxExtend( target, src ) { + var key, deep, + flatOptions = jQuery.ajaxSettings.flatOptions || {}; + + for ( key in src ) { + if ( src[ key ] !== undefined ) { + ( flatOptions[ key ] ? target : ( deep || ( deep = {} ) ) )[ key ] = src[ key ]; + } + } + if ( deep ) { + jQuery.extend( true, target, deep ); + } + + return target; +} + +/* Handles responses to an ajax request: + * - finds the right dataType (mediates between content-type and expected dataType) + * - returns the corresponding response + */ +function ajaxHandleResponses( s, jqXHR, responses ) { + + var ct, type, finalDataType, firstDataType, + contents = s.contents, + dataTypes = s.dataTypes; + + // Remove auto dataType and get content-type in the process + while ( dataTypes[ 0 ] === "*" ) { + dataTypes.shift(); + if ( ct === undefined ) { + ct = s.mimeType || jqXHR.getResponseHeader( "Content-Type" ); + } + } + + // Check if we're dealing with a known content-type + if ( ct ) { + for ( type in contents ) { + if ( contents[ type ] && contents[ type ].test( ct ) ) { + dataTypes.unshift( type ); + break; + } + } + } + + // Check to see if we have a response for the expected dataType + if ( dataTypes[ 0 ] in responses ) { + finalDataType = dataTypes[ 0 ]; + } else { + + // Try convertible dataTypes + for ( type in responses ) { + if ( !dataTypes[ 0 ] || s.converters[ type + " " + dataTypes[ 0 ] ] ) { + finalDataType = type; + break; + } + if ( !firstDataType ) { + firstDataType = type; + } + } + + // Or just use first one + finalDataType = finalDataType || firstDataType; + } + + // If we found a dataType + // We add the dataType to the list if needed + // and return the corresponding response + if ( finalDataType ) { + if ( finalDataType !== dataTypes[ 0 ] ) { + dataTypes.unshift( finalDataType ); + } + return responses[ finalDataType ]; + } +} + +/* Chain conversions given the request and the original response + * Also sets the responseXXX fields on the jqXHR instance + */ +function ajaxConvert( s, response, jqXHR, isSuccess ) { + var conv2, current, conv, tmp, prev, + converters = {}, + + // Work with a copy of dataTypes in case we need to modify it for conversion + dataTypes = s.dataTypes.slice(); + + // Create converters map with lowercased keys + if ( dataTypes[ 1 ] ) { + for ( conv in s.converters ) { + converters[ conv.toLowerCase() ] = s.converters[ conv ]; + } + } + + current = dataTypes.shift(); + + // Convert to each sequential dataType + while ( current ) { + + if ( s.responseFields[ current ] ) { + jqXHR[ s.responseFields[ current ] ] = response; + } + + // Apply the dataFilter if provided + if ( !prev && isSuccess && s.dataFilter ) { + response = s.dataFilter( response, s.dataType ); + } + + prev = current; + current = dataTypes.shift(); + + if ( current ) { + + // There's only work to do if current dataType is non-auto + if ( current === "*" ) { + + current = prev; + + // Convert response if prev dataType is non-auto and differs from current + } else if ( prev !== "*" && prev !== current ) { + + // Seek a direct converter + conv = converters[ prev + " " + current ] || converters[ "* " + current ]; + + // If none found, seek a pair + if ( !conv ) { + for ( conv2 in converters ) { + + // If conv2 outputs current + tmp = conv2.split( " " ); + if ( tmp[ 1 ] === current ) { + + // If prev can be converted to accepted input + conv = converters[ prev + " " + tmp[ 0 ] ] || + converters[ "* " + tmp[ 0 ] ]; + if ( conv ) { + + // Condense equivalence converters + if ( conv === true ) { + conv = converters[ conv2 ]; + + // Otherwise, insert the intermediate dataType + } else if ( converters[ conv2 ] !== true ) { + current = tmp[ 0 ]; + dataTypes.unshift( tmp[ 1 ] ); + } + break; + } + } + } + } + + // Apply converter (if not an equivalence) + if ( conv !== true ) { + + // Unless errors are allowed to bubble, catch and return them + if ( conv && s.throws ) { + response = conv( response ); + } else { + try { + response = conv( response ); + } catch ( e ) { + return { + state: "parsererror", + error: conv ? e : "No conversion from " + prev + " to " + current + }; + } + } + } + } + } + } + + return { state: "success", data: response }; +} + +jQuery.extend( { + + // Counter for holding the number of active queries + active: 0, + + // Last-Modified header cache for next request + lastModified: {}, + etag: {}, + + ajaxSettings: { + url: location.href, + type: "GET", + isLocal: rlocalProtocol.test( location.protocol ), + global: true, + processData: true, + async: true, + contentType: "application/x-www-form-urlencoded; charset=UTF-8", + + /* + timeout: 0, + data: null, + dataType: null, + username: null, + password: null, + cache: null, + throws: false, + traditional: false, + headers: {}, + */ + + accepts: { + "*": allTypes, + text: "text/plain", + html: "text/html", + xml: "application/xml, text/xml", + json: "application/json, text/javascript" + }, + + contents: { + xml: /\bxml\b/, + html: /\bhtml/, + json: /\bjson\b/ + }, + + responseFields: { + xml: "responseXML", + text: "responseText", + json: "responseJSON" + }, + + // Data converters + // Keys separate source (or catchall "*") and destination types with a single space + converters: { + + // Convert anything to text + "* text": String, + + // Text to html (true = no transformation) + "text html": true, + + // Evaluate text as a json expression + "text json": JSON.parse, + + // Parse text as xml + "text xml": jQuery.parseXML + }, + + // For options that shouldn't be deep extended: + // you can add your own custom options here if + // and when you create one that shouldn't be + // deep extended (see ajaxExtend) + flatOptions: { + url: true, + context: true + } + }, + + // Creates a full fledged settings object into target + // with both ajaxSettings and settings fields. + // If target is omitted, writes into ajaxSettings. + ajaxSetup: function( target, settings ) { + return settings ? + + // Building a settings object + ajaxExtend( ajaxExtend( target, jQuery.ajaxSettings ), settings ) : + + // Extending ajaxSettings + ajaxExtend( jQuery.ajaxSettings, target ); + }, + + ajaxPrefilter: addToPrefiltersOrTransports( prefilters ), + ajaxTransport: addToPrefiltersOrTransports( transports ), + + // Main method + ajax: function( url, options ) { + + // If url is an object, simulate pre-1.5 signature + if ( typeof url === "object" ) { + options = url; + url = undefined; + } + + // Force options to be an object + options = options || {}; + + var transport, + + // URL without anti-cache param + cacheURL, + + // Response headers + responseHeadersString, + responseHeaders, + + // timeout handle + timeoutTimer, + + // Url cleanup var + urlAnchor, + + // Request state (becomes false upon send and true upon completion) + completed, + + // To know if global events are to be dispatched + fireGlobals, + + // Loop variable + i, + + // uncached part of the url + uncached, + + // Create the final options object + s = jQuery.ajaxSetup( {}, options ), + + // Callbacks context + callbackContext = s.context || s, + + // Context for global events is callbackContext if it is a DOM node or jQuery collection + globalEventContext = s.context && + ( callbackContext.nodeType || callbackContext.jquery ) ? + jQuery( callbackContext ) : + jQuery.event, + + // Deferreds + deferred = jQuery.Deferred(), + completeDeferred = jQuery.Callbacks( "once memory" ), + + // Status-dependent callbacks + statusCode = s.statusCode || {}, + + // Headers (they are sent all at once) + requestHeaders = {}, + requestHeadersNames = {}, + + // Default abort message + strAbort = "canceled", + + // Fake xhr + jqXHR = { + readyState: 0, + + // Builds headers hashtable if needed + getResponseHeader: function( key ) { + var match; + if ( completed ) { + if ( !responseHeaders ) { + responseHeaders = {}; + while ( ( match = rheaders.exec( responseHeadersString ) ) ) { + responseHeaders[ match[ 1 ].toLowerCase() + " " ] = + ( responseHeaders[ match[ 1 ].toLowerCase() + " " ] || [] ) + .concat( match[ 2 ] ); + } + } + match = responseHeaders[ key.toLowerCase() + " " ]; + } + return match == null ? null : match.join( ", " ); + }, + + // Raw string + getAllResponseHeaders: function() { + return completed ? responseHeadersString : null; + }, + + // Caches the header + setRequestHeader: function( name, value ) { + if ( completed == null ) { + name = requestHeadersNames[ name.toLowerCase() ] = + requestHeadersNames[ name.toLowerCase() ] || name; + requestHeaders[ name ] = value; + } + return this; + }, + + // Overrides response content-type header + overrideMimeType: function( type ) { + if ( completed == null ) { + s.mimeType = type; + } + return this; + }, + + // Status-dependent callbacks + statusCode: function( map ) { + var code; + if ( map ) { + if ( completed ) { + + // Execute the appropriate callbacks + jqXHR.always( map[ jqXHR.status ] ); + } else { + + // Lazy-add the new callbacks in a way that preserves old ones + for ( code in map ) { + statusCode[ code ] = [ statusCode[ code ], map[ code ] ]; + } + } + } + return this; + }, + + // Cancel the request + abort: function( statusText ) { + var finalText = statusText || strAbort; + if ( transport ) { + transport.abort( finalText ); + } + done( 0, finalText ); + return this; + } + }; + + // Attach deferreds + deferred.promise( jqXHR ); + + // Add protocol if not provided (prefilters might expect it) + // Handle falsy url in the settings object (#10093: consistency with old signature) + // We also use the url parameter if available + s.url = ( ( url || s.url || location.href ) + "" ) + .replace( rprotocol, location.protocol + "//" ); + + // Alias method option to type as per ticket #12004 + s.type = options.method || options.type || s.method || s.type; + + // Extract dataTypes list + s.dataTypes = ( s.dataType || "*" ).toLowerCase().match( rnothtmlwhite ) || [ "" ]; + + // A cross-domain request is in order when the origin doesn't match the current origin. + if ( s.crossDomain == null ) { + urlAnchor = document.createElement( "a" ); + + // Support: IE <=8 - 11, Edge 12 - 15 + // IE throws exception on accessing the href property if url is malformed, + // e.g. http://example.com:80x/ + try { + urlAnchor.href = s.url; + + // Support: IE <=8 - 11 only + // Anchor's host property isn't correctly set when s.url is relative + urlAnchor.href = urlAnchor.href; + s.crossDomain = originAnchor.protocol + "//" + originAnchor.host !== + urlAnchor.protocol + "//" + urlAnchor.host; + } catch ( e ) { + + // If there is an error parsing the URL, assume it is crossDomain, + // it can be rejected by the transport if it is invalid + s.crossDomain = true; + } + } + + // Convert data if not already a string + if ( s.data && s.processData && typeof s.data !== "string" ) { + s.data = jQuery.param( s.data, s.traditional ); + } + + // Apply prefilters + inspectPrefiltersOrTransports( prefilters, s, options, jqXHR ); + + // If request was aborted inside a prefilter, stop there + if ( completed ) { + return jqXHR; + } + + // We can fire global events as of now if asked to + // Don't fire events if jQuery.event is undefined in an AMD-usage scenario (#15118) + fireGlobals = jQuery.event && s.global; + + // Watch for a new set of requests + if ( fireGlobals && jQuery.active++ === 0 ) { + jQuery.event.trigger( "ajaxStart" ); + } + + // Uppercase the type + s.type = s.type.toUpperCase(); + + // Determine if request has content + s.hasContent = !rnoContent.test( s.type ); + + // Save the URL in case we're toying with the If-Modified-Since + // and/or If-None-Match header later on + // Remove hash to simplify url manipulation + cacheURL = s.url.replace( rhash, "" ); + + // More options handling for requests with no content + if ( !s.hasContent ) { + + // Remember the hash so we can put it back + uncached = s.url.slice( cacheURL.length ); + + // If data is available and should be processed, append data to url + if ( s.data && ( s.processData || typeof s.data === "string" ) ) { + cacheURL += ( rquery.test( cacheURL ) ? "&" : "?" ) + s.data; + + // #9682: remove data so that it's not used in an eventual retry + delete s.data; + } + + // Add or update anti-cache param if needed + if ( s.cache === false ) { + cacheURL = cacheURL.replace( rantiCache, "$1" ); + uncached = ( rquery.test( cacheURL ) ? "&" : "?" ) + "_=" + ( nonce.guid++ ) + + uncached; + } + + // Put hash and anti-cache on the URL that will be requested (gh-1732) + s.url = cacheURL + uncached; + + // Change '%20' to '+' if this is encoded form body content (gh-2658) + } else if ( s.data && s.processData && + ( s.contentType || "" ).indexOf( "application/x-www-form-urlencoded" ) === 0 ) { + s.data = s.data.replace( r20, "+" ); + } + + // Set the If-Modified-Since and/or If-None-Match header, if in ifModified mode. + if ( s.ifModified ) { + if ( jQuery.lastModified[ cacheURL ] ) { + jqXHR.setRequestHeader( "If-Modified-Since", jQuery.lastModified[ cacheURL ] ); + } + if ( jQuery.etag[ cacheURL ] ) { + jqXHR.setRequestHeader( "If-None-Match", jQuery.etag[ cacheURL ] ); + } + } + + // Set the correct header, if data is being sent + if ( s.data && s.hasContent && s.contentType !== false || options.contentType ) { + jqXHR.setRequestHeader( "Content-Type", s.contentType ); + } + + // Set the Accepts header for the server, depending on the dataType + jqXHR.setRequestHeader( + "Accept", + s.dataTypes[ 0 ] && s.accepts[ s.dataTypes[ 0 ] ] ? + s.accepts[ s.dataTypes[ 0 ] ] + + ( s.dataTypes[ 0 ] !== "*" ? ", " + allTypes + "; q=0.01" : "" ) : + s.accepts[ "*" ] + ); + + // Check for headers option + for ( i in s.headers ) { + jqXHR.setRequestHeader( i, s.headers[ i ] ); + } + + // Allow custom headers/mimetypes and early abort + if ( s.beforeSend && + ( s.beforeSend.call( callbackContext, jqXHR, s ) === false || completed ) ) { + + // Abort if not done already and return + return jqXHR.abort(); + } + + // Aborting is no longer a cancellation + strAbort = "abort"; + + // Install callbacks on deferreds + completeDeferred.add( s.complete ); + jqXHR.done( s.success ); + jqXHR.fail( s.error ); + + // Get transport + transport = inspectPrefiltersOrTransports( transports, s, options, jqXHR ); + + // If no transport, we auto-abort + if ( !transport ) { + done( -1, "No Transport" ); + } else { + jqXHR.readyState = 1; + + // Send global event + if ( fireGlobals ) { + globalEventContext.trigger( "ajaxSend", [ jqXHR, s ] ); + } + + // If request was aborted inside ajaxSend, stop there + if ( completed ) { + return jqXHR; + } + + // Timeout + if ( s.async && s.timeout > 0 ) { + timeoutTimer = window.setTimeout( function() { + jqXHR.abort( "timeout" ); + }, s.timeout ); + } + + try { + completed = false; + transport.send( requestHeaders, done ); + } catch ( e ) { + + // Rethrow post-completion exceptions + if ( completed ) { + throw e; + } + + // Propagate others as results + done( -1, e ); + } + } + + // Callback for when everything is done + function done( status, nativeStatusText, responses, headers ) { + var isSuccess, success, error, response, modified, + statusText = nativeStatusText; + + // Ignore repeat invocations + if ( completed ) { + return; + } + + completed = true; + + // Clear timeout if it exists + if ( timeoutTimer ) { + window.clearTimeout( timeoutTimer ); + } + + // Dereference transport for early garbage collection + // (no matter how long the jqXHR object will be used) + transport = undefined; + + // Cache response headers + responseHeadersString = headers || ""; + + // Set readyState + jqXHR.readyState = status > 0 ? 4 : 0; + + // Determine if successful + isSuccess = status >= 200 && status < 300 || status === 304; + + // Get response data + if ( responses ) { + response = ajaxHandleResponses( s, jqXHR, responses ); + } + + // Use a noop converter for missing script but not if jsonp + if ( !isSuccess && + jQuery.inArray( "script", s.dataTypes ) > -1 && + jQuery.inArray( "json", s.dataTypes ) < 0 ) { + s.converters[ "text script" ] = function() {}; + } + + // Convert no matter what (that way responseXXX fields are always set) + response = ajaxConvert( s, response, jqXHR, isSuccess ); + + // If successful, handle type chaining + if ( isSuccess ) { + + // Set the If-Modified-Since and/or If-None-Match header, if in ifModified mode. + if ( s.ifModified ) { + modified = jqXHR.getResponseHeader( "Last-Modified" ); + if ( modified ) { + jQuery.lastModified[ cacheURL ] = modified; + } + modified = jqXHR.getResponseHeader( "etag" ); + if ( modified ) { + jQuery.etag[ cacheURL ] = modified; + } + } + + // if no content + if ( status === 204 || s.type === "HEAD" ) { + statusText = "nocontent"; + + // if not modified + } else if ( status === 304 ) { + statusText = "notmodified"; + + // If we have data, let's convert it + } else { + statusText = response.state; + success = response.data; + error = response.error; + isSuccess = !error; + } + } else { + + // Extract error from statusText and normalize for non-aborts + error = statusText; + if ( status || !statusText ) { + statusText = "error"; + if ( status < 0 ) { + status = 0; + } + } + } + + // Set data for the fake xhr object + jqXHR.status = status; + jqXHR.statusText = ( nativeStatusText || statusText ) + ""; + + // Success/Error + if ( isSuccess ) { + deferred.resolveWith( callbackContext, [ success, statusText, jqXHR ] ); + } else { + deferred.rejectWith( callbackContext, [ jqXHR, statusText, error ] ); + } + + // Status-dependent callbacks + jqXHR.statusCode( statusCode ); + statusCode = undefined; + + if ( fireGlobals ) { + globalEventContext.trigger( isSuccess ? "ajaxSuccess" : "ajaxError", + [ jqXHR, s, isSuccess ? success : error ] ); + } + + // Complete + completeDeferred.fireWith( callbackContext, [ jqXHR, statusText ] ); + + if ( fireGlobals ) { + globalEventContext.trigger( "ajaxComplete", [ jqXHR, s ] ); + + // Handle the global AJAX counter + if ( !( --jQuery.active ) ) { + jQuery.event.trigger( "ajaxStop" ); + } + } + } + + return jqXHR; + }, + + getJSON: function( url, data, callback ) { + return jQuery.get( url, data, callback, "json" ); + }, + + getScript: function( url, callback ) { + return jQuery.get( url, undefined, callback, "script" ); + } +} ); + +jQuery.each( [ "get", "post" ], function( _i, method ) { + jQuery[ method ] = function( url, data, callback, type ) { + + // Shift arguments if data argument was omitted + if ( isFunction( data ) ) { + type = type || callback; + callback = data; + data = undefined; + } + + // The url can be an options object (which then must have .url) + return jQuery.ajax( jQuery.extend( { + url: url, + type: method, + dataType: type, + data: data, + success: callback + }, jQuery.isPlainObject( url ) && url ) ); + }; +} ); + +jQuery.ajaxPrefilter( function( s ) { + var i; + for ( i in s.headers ) { + if ( i.toLowerCase() === "content-type" ) { + s.contentType = s.headers[ i ] || ""; + } + } +} ); + + +jQuery._evalUrl = function( url, options, doc ) { + return jQuery.ajax( { + url: url, + + // Make this explicit, since user can override this through ajaxSetup (#11264) + type: "GET", + dataType: "script", + cache: true, + async: false, + global: false, + + // Only evaluate the response if it is successful (gh-4126) + // dataFilter is not invoked for failure responses, so using it instead + // of the default converter is kludgy but it works. + converters: { + "text script": function() {} + }, + dataFilter: function( response ) { + jQuery.globalEval( response, options, doc ); + } + } ); +}; + + +jQuery.fn.extend( { + wrapAll: function( html ) { + var wrap; + + if ( this[ 0 ] ) { + if ( isFunction( html ) ) { + html = html.call( this[ 0 ] ); + } + + // The elements to wrap the target around + wrap = jQuery( html, this[ 0 ].ownerDocument ).eq( 0 ).clone( true ); + + if ( this[ 0 ].parentNode ) { + wrap.insertBefore( this[ 0 ] ); + } + + wrap.map( function() { + var elem = this; + + while ( elem.firstElementChild ) { + elem = elem.firstElementChild; + } + + return elem; + } ).append( this ); + } + + return this; + }, + + wrapInner: function( html ) { + if ( isFunction( html ) ) { + return this.each( function( i ) { + jQuery( this ).wrapInner( html.call( this, i ) ); + } ); + } + + return this.each( function() { + var self = jQuery( this ), + contents = self.contents(); + + if ( contents.length ) { + contents.wrapAll( html ); + + } else { + self.append( html ); + } + } ); + }, + + wrap: function( html ) { + var htmlIsFunction = isFunction( html ); + + return this.each( function( i ) { + jQuery( this ).wrapAll( htmlIsFunction ? html.call( this, i ) : html ); + } ); + }, + + unwrap: function( selector ) { + this.parent( selector ).not( "body" ).each( function() { + jQuery( this ).replaceWith( this.childNodes ); + } ); + return this; + } +} ); + + +jQuery.expr.pseudos.hidden = function( elem ) { + return !jQuery.expr.pseudos.visible( elem ); +}; +jQuery.expr.pseudos.visible = function( elem ) { + return !!( elem.offsetWidth || elem.offsetHeight || elem.getClientRects().length ); +}; + + + + +jQuery.ajaxSettings.xhr = function() { + try { + return new window.XMLHttpRequest(); + } catch ( e ) {} +}; + +var xhrSuccessStatus = { + + // File protocol always yields status code 0, assume 200 + 0: 200, + + // Support: IE <=9 only + // #1450: sometimes IE returns 1223 when it should be 204 + 1223: 204 + }, + xhrSupported = jQuery.ajaxSettings.xhr(); + +support.cors = !!xhrSupported && ( "withCredentials" in xhrSupported ); +support.ajax = xhrSupported = !!xhrSupported; + +jQuery.ajaxTransport( function( options ) { + var callback, errorCallback; + + // Cross domain only allowed if supported through XMLHttpRequest + if ( support.cors || xhrSupported && !options.crossDomain ) { + return { + send: function( headers, complete ) { + var i, + xhr = options.xhr(); + + xhr.open( + options.type, + options.url, + options.async, + options.username, + options.password + ); + + // Apply custom fields if provided + if ( options.xhrFields ) { + for ( i in options.xhrFields ) { + xhr[ i ] = options.xhrFields[ i ]; + } + } + + // Override mime type if needed + if ( options.mimeType && xhr.overrideMimeType ) { + xhr.overrideMimeType( options.mimeType ); + } + + // X-Requested-With header + // For cross-domain requests, seeing as conditions for a preflight are + // akin to a jigsaw puzzle, we simply never set it to be sure. + // (it can always be set on a per-request basis or even using ajaxSetup) + // For same-domain requests, won't change header if already provided. + if ( !options.crossDomain && !headers[ "X-Requested-With" ] ) { + headers[ "X-Requested-With" ] = "XMLHttpRequest"; + } + + // Set headers + for ( i in headers ) { + xhr.setRequestHeader( i, headers[ i ] ); + } + + // Callback + callback = function( type ) { + return function() { + if ( callback ) { + callback = errorCallback = xhr.onload = + xhr.onerror = xhr.onabort = xhr.ontimeout = + xhr.onreadystatechange = null; + + if ( type === "abort" ) { + xhr.abort(); + } else if ( type === "error" ) { + + // Support: IE <=9 only + // On a manual native abort, IE9 throws + // errors on any property access that is not readyState + if ( typeof xhr.status !== "number" ) { + complete( 0, "error" ); + } else { + complete( + + // File: protocol always yields status 0; see #8605, #14207 + xhr.status, + xhr.statusText + ); + } + } else { + complete( + xhrSuccessStatus[ xhr.status ] || xhr.status, + xhr.statusText, + + // Support: IE <=9 only + // IE9 has no XHR2 but throws on binary (trac-11426) + // For XHR2 non-text, let the caller handle it (gh-2498) + ( xhr.responseType || "text" ) !== "text" || + typeof xhr.responseText !== "string" ? + { binary: xhr.response } : + { text: xhr.responseText }, + xhr.getAllResponseHeaders() + ); + } + } + }; + }; + + // Listen to events + xhr.onload = callback(); + errorCallback = xhr.onerror = xhr.ontimeout = callback( "error" ); + + // Support: IE 9 only + // Use onreadystatechange to replace onabort + // to handle uncaught aborts + if ( xhr.onabort !== undefined ) { + xhr.onabort = errorCallback; + } else { + xhr.onreadystatechange = function() { + + // Check readyState before timeout as it changes + if ( xhr.readyState === 4 ) { + + // Allow onerror to be called first, + // but that will not handle a native abort + // Also, save errorCallback to a variable + // as xhr.onerror cannot be accessed + window.setTimeout( function() { + if ( callback ) { + errorCallback(); + } + } ); + } + }; + } + + // Create the abort callback + callback = callback( "abort" ); + + try { + + // Do send the request (this may raise an exception) + xhr.send( options.hasContent && options.data || null ); + } catch ( e ) { + + // #14683: Only rethrow if this hasn't been notified as an error yet + if ( callback ) { + throw e; + } + } + }, + + abort: function() { + if ( callback ) { + callback(); + } + } + }; + } +} ); + + + + +// Prevent auto-execution of scripts when no explicit dataType was provided (See gh-2432) +jQuery.ajaxPrefilter( function( s ) { + if ( s.crossDomain ) { + s.contents.script = false; + } +} ); + +// Install script dataType +jQuery.ajaxSetup( { + accepts: { + script: "text/javascript, application/javascript, " + + "application/ecmascript, application/x-ecmascript" + }, + contents: { + script: /\b(?:java|ecma)script\b/ + }, + converters: { + "text script": function( text ) { + jQuery.globalEval( text ); + return text; + } + } +} ); + +// Handle cache's special case and crossDomain +jQuery.ajaxPrefilter( "script", function( s ) { + if ( s.cache === undefined ) { + s.cache = false; + } + if ( s.crossDomain ) { + s.type = "GET"; + } +} ); + +// Bind script tag hack transport +jQuery.ajaxTransport( "script", function( s ) { + + // This transport only deals with cross domain or forced-by-attrs requests + if ( s.crossDomain || s.scriptAttrs ) { + var script, callback; + return { + send: function( _, complete ) { + script = jQuery( " + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

bastion.conf

+
+
+

Note

+

The Bastion has a lot of configuration options so that you can tailor it +to your needs. However, if you're just beggining 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 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.

+ +
+
+

SSH Policies options

+

All the options related to the SSH configuration and policies, both for ingress and egress connections.

+ +
+
+

Global network policies options

+

Those options can set a few global network policies to be applied bastion-wide.

+ +
+
+

Logging options

+

Options to customize how logs should be produced.

+ +
+
+

Other ingress policies options

+

Policies applying to the ingress connections

+ +
+
+

Other egress policies options

+

Policies applying to the egress connections

+ +
+
+

Session policies options

+

Options to customize the established sessions behaviour

+ +
+
+

Account policies options

+

Policies applying to the bastion accounts themselves

+ +
+
+

Other options options

+

These options are either discouraged (in which case this is explained in the description) or rarely need to be modified.

+ +
+
+
+

Option Reference

+
+

Main Options

+
+

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.

+
+
+

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

+
+
+

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.

+
+
+

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.

+
+
+

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. Don't forget to add them to the osh-superowner group too (system-wise), or they won't really be considered as "Super Owners": this is an additional security measure against privilege escalation.

+
+
+
+

SSH Policies

+
+

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: rsa, ecdsa, ed25519, ecdsa-sk, ed25519-sk, note that some of those might not be supported by your current version of OpenSSH: unsupported algorithms are automatically omitted at runtime.

+
+
+

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: 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.

+
+
+

minimumIngressRsaKeySize

+
+
Type
+

int > 0

+
+
Default
+

2048

+
+
+

The minimum allowed size for ingress RSA keys (user->bastion). Sane values range from 2048 to 4096.

+
+
+

maximumIngressRsaKeySize

+
+
Type
+

int > 0

+
+
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.

+
+
+

minimumEgressRsaKeySize

+
+
Type
+

int > 0

+
+
Default
+

2048

+
+
+

The minimum allowed size for egress RSA keys (bastion->server). Sane values range from 2048 to 4096.

+
+
+

maximumEgressRsaKeySize

+
+
Type
+

int > 0

+
+
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.

+
+
+

defaultAccountEgressKeyAlgorithm

+
+
Type
+

string

+
+
Default
+

"rsa"

+
+
+

The default algorithm to use to create the egress key of a newly created account

+
+
+

defaultAccountEgressKeySize

+
+
Type
+

int > 0

+
+
Default
+

4096

+
+
+

The default size to use to create the egress key of a newly created account (also see defaultAccountEgressKeyAlgorithm)

+
+
+

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.

+
+
+

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+).

+
+
+

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+).

+
+
+

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

+
+

dnsSupportLevel

+
+
Type
+

integer between 0 and 2

+
+
Default
+

2

+
+
+
+
If set to 0, The Bastion will never attempt to do DNS or reverse-DNS resolutions, and return an error if you request connection to a hostname instead of an IP. Use this if you know there's no working DNS in your environment and only use IPs everywhere.

If set to 1, The Bastion will not attempt to do DNS or reverse-DNS resolutions unless you force it to (i.e. by requesting connection to a hostname instead of an IP). You may use this if for example you have well-known hostnames in /etc/hosts, but don't have a working DNS (which would imply that reverse-DNS resolutions will always fail). +If set to 2, The Bastion will make the assumption that you have a working DNS setup, and will do DNS and reverse-DNS resolutions normally.

+
+
+
+
+

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.

+
+
+

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.

+
+
+

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

+
+

enableSyslog

+
+
Type
+

boolean

+
+
Default
+

true

+
+
+

If enabled, we'll send logs through syslog, don't forget to setup your syslog daemon!. You can also adjust syslogFacility and syslogDescription below, to match your syslog configuration. Note that the provided syslog-ng templates work with the default values left as-is.

+
+
+

syslogFacility

+
+
Type
+

string

+
+
Default
+

"local7"

+
+
+

Sets the facility that will be used for syslog.

+
+
+

syslogDescription

+
+
Type
+

string

+
+
Default
+

"bastion"

+
+
+

Sets the description that will be used for syslog.

+
+
+

enableGlobalAccessLog

+
+
Type
+

boolean

+
+
Default
+

true

+
+
+

If enabled, all open and close logs will be written to /home/logkeeper/global-log-YYYYMM.log. Those are also logged through syslog if enableSyslog is set.

+
+
+

enableAccountAccessLog

+
+
Type
+

boolean

+
+
Default
+

true

+
+
+

If enabled, all open and close logs will be written to the corresponding user's home in /home/USER/USER-log-YYYYMM.log. Those are also logged through syslog if enableSyslog is set.

+
+
+

enableGlobalSqlLog

+
+
Type
+

boolean

+
+
Default
+

true

+
+
+

If enabled, all access logs (corresponding to the open and close events) will be written in a short SQL format, as one row per access, to /home/logkeeper/global-log-YYYYMM.sqlite.

+
+
+

enableAccountSqlLog

+
+
Type
+

boolean

+
+
Default
+

true

+
+
+

If enabled, all access logs (corresponding to the open and close events) will be written in a detailed SQL format, as one row per access, in the corresponding user's home to /home/USER/USER-log-YYYYMM.sqlite. If you want to use selfListSessions and/or selfPlaySession, this is required.

+
+
+

ttyrecFilenameFormat

+
+
Type
+

string

+
+
Default
+

"%Y-%m-%d.%H-%M-%S.#usec#.&uniqid.&account.&user.&ip.&port.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.

+
+
+

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.

+
+
+

ttyrecStealthStdoutPattern

+
+
Type
+

regex

+
+
Default
+

""

+
+
Example
+

"^rsync --server .+"

+
+
+

When this is set to a non-falsy value, this is expected to be a string that will be converted to a regex which will be matched against a potential remote command specified when connecting through SSH to a remote server. If the regex matches, then we'll instruct ttyrec to NOT record stdout for this session.

+
+
+
+

Other ingress policies

+
+

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).

+
+
+

ingressKeysFromAllowOverride

+
+
Type
+

boolean

+
+
Default
+

false

+
+
+

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

+
+

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.

+
+
+

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.

+
+
+

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.

+
+
+

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.

+
+
+

telnetAllowed

+
+
Type
+

boolean

+
+
Default
+

false

+
+
+

If set to true, will allow telnet egress connections (-e / --telnet).

+
+
+
+

Session policies

+
+

displayLastLogin

+
+
Type
+

boolean

+
+
Default
+

true

+
+
+

If true, display their last login information on connection to your users.

+
+
+

fanciness

+
+
Type
+

string

+
+
Default
+

full

+
+
+

Customize to which extent the text output by the program will use decorations to enhance human-friendliness and highlight warnings or critical messages. Note that if a given session's terminal doesn't advertise UTF-8 support, UTF-8 will not be used, regardless of what is set here.

+
    +

  • "none": Text will only consist of us-ascii characters

    • +

  • "basic": UTF-8 characters will be used to draw tables, instead of ---'s, among other things

    • +

  • "full": Some emoticons may appear to highlight important messages

    • +
+
+
+

interactiveModeAllowed

+
+
Type
+

boolean

+
+
Default
+

true

+
+
+

If set to true, --interactive mode is allowed. Otherwise, this feature is disabled.

+
+
+

interactiveModeTimeout

+
+
Type
+

int >= 0 (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).

+
+
+

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).

+
+
+

interactiveModeProactiveMFAenabled

+
+
Type
+

boolean

+
+
Default
+

true

+
+
+

If enabled, the mfa command is allowed in interactive mode, to trigger a proactive MFA challenge, so that subsequent commands normally requiring MFA won't ask for it again.

+
+
+

interactiveModeProactiveMFAexpiration

+
+
Type
+

int >= 0 (seconds)

+
+
Default
+

900

+
+
+

If the above interactiveModeProactiveMFAenabled option is true, then this is the amount of seconds after which the proactive MFA mode is automatically disengaged.

+
+
+

idleLockTimeout

+
+
Type
+

int >= 0 (seconds)

+
+
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.

+
+
+

idleKillTimeout

+
+
Type
+

int >= 0 (seconds)

+
+
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).

+
+
+

warnBeforeLockSeconds

+
+
Type
+

int >= 0 (seconds)

+
+
Default
+

0

+
+
+

If set to a positive value >0, the number of seconds before idleLockTimeout where the user will receive a warning message telling them about the upcoming lock of his session. Don't enable this (by setting a non-zero value) if idleLockTimeout is disabled (set to zero).

+
+
+

warnBeforeKillSeconds

+
+
Type
+

int >= 0 (seconds)

+
+
Default
+

0

+
+
+

If set to a positive value >0, the number of seconds before idleKillTimeout where the user will receive a warning message telling them about the upcoming kill of his session. Don't enable this (by setting a non-zero value) if idleKillTimeout is disabled (set to zero).

+
+
+

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).

+
+
+

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.

+
+
+

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

+
+

accountMaxInactiveDays

+
+
Type
+

int >= 0 (days)

+
+
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).

+
+
+

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.

+
+
+

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.

+
+
+

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)

+
+
+

ingressRequirePIV

+
+
Type
+

boolean

+
+
Default
+

false

+
+
+

When set to true, only PIV-enabled SSH keys will be able to be added with selfAddIngressKey, hence ensuring that an SSH key generated on a computer, and not within a PIV-compatible hardware token, can't be used to access The Bastion. If you only want to enable this on a per-account basis, leave this to false and set the flag on said accounts using accountPIV instead. When set to false, will not require PIV-enabled SSH keys to be added by selfAddIngressKey. If you have no idea what PIV keys are, leave this to false, this is what you want.

+
+
+

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 themselves 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)

    • +
+
+
+

MFAPasswordMinDays

+
+
Type
+

int >= 0 (days)

+
+
Default
+

0

+
+
+

For the PAM UNIX password MFA, sets the min amount of days between two password changes (see chage -m)

+
+
+

MFAPasswordMaxDays

+
+
Type
+

int >= 0 (days)

+
+
Default
+

90

+
+
+

For the PAM UNIX password MFA, sets the max amount of days after which the password must be changed (see chage -M)

+
+
+

MFAPasswordWarnDays

+
+
Type
+

int >= 0 (days)

+
+
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)

+
+
+

MFAPasswordInactiveDays

+
+
Type
+

int >= -1 (days)

+
+
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

+
+
+

MFAPostCommand

+
+
Type
+

array of strings (a valid system command)

+
+
Default
+

[]

+
+
Example
+

["sudo","-n","-u","root","--","/sbin/pam_tally2","-u","%ACCOUNT%","-r"] or ["/usr/sbin/faillock","--reset"]

+
+
+

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 or pam_faillock 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. +Note that usually, pam_tally2 can only be used by root (hence might require the proper sudoers configuration), while faillock can directly be used by unprivileged users to reset their counter.

+
+
+

TOTPProvider

+
+
Type
+

string

+
+
Default
+

'google-authenticator'

+
+
+

Defines which is the provider of the TOTP MFA, that will be used for the (self|account)MFA(Setup|Reset)TOTP commands. Allowed values are: +- none: no TOTP providers are defined, the corresponding setup commands won't be available. +- google-authenticator: the pam_google_authenticator.so module will be used, along with its corresponding setup binary. This is the default, for backward compatibility reasons. This is also what is configured in the provided pam templates. +- duo: enable the use of the Duo PAM module (pam_duo.so), of course you need to set it up correctly in your /etc/pam.d/sshd file.

+
+
+
+

Other options

+
+

accountUidMin

+
+
Type
+

int >= 100

+
+
Default
+

2000

+
+
+

Minimum allowed UID for accounts on this bastion. Hardcoded > 100 even if configured for less.

+
+
+

accountUidMax

+
+
Type
+

int > 0

+
+
Default
+

99999

+
+
+

Maximum allowed UID for accounts on this bastion.

+
+
+

ttyrecGroupIdOffset

+
+
Type
+

int > 0

+
+
Default
+

100000

+
+
+

Offset to apply on user group uid to create its -tty group, should be > accountUidMax - accountUidMin to ensure there is no overlap.

+
+
+

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.

+
+
+

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.

+
+
+

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.

+
+
+

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.

+
+
+

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).

+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/administration/configuration/index.html b/administration/configuration/index.html new file mode 100644 index 0000000..98836d6 --- /dev/null +++ b/administration/configuration/index.html @@ -0,0 +1,194 @@ + + + + + + + Configuration files — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Configuration files

+
+

Main configuration files

+

These config files should be reviewed and adapted for the environment in which +you're deploying The Bastion. The doc:bastion_conf is the only one that is +mandatory to get you started. You should however review the other ones before +going into production.

+
+ +
+
+
+

Configuration files for satellite scripts

+

These config files govern the behavior of satellite scripts that handle +background tasks of The Bastion. Most of the time, there is no need to alter +the configuration as sane defaults are already built in.

+
+ +
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/administration/configuration/osh-backup-acl-keys_conf.html b/administration/configuration/osh-backup-acl-keys_conf.html new file mode 100644 index 0000000..b86c39d --- /dev/null +++ b/administration/configuration/osh-backup-acl-keys_conf.html @@ -0,0 +1,376 @@ + + + + + + + osh-backup-acl-keys.conf — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

osh-backup-acl-keys.conf

+
+
+

Note

+

This script is called by cron and is responsible +for backing up the bastion configuration, users & groups lists, +credentials, and everything needed to be able to restore a functioning +bastion from scratch.

+
+
+

Warning

+

If left unconfigured, this script won't do anything, +and you won't have backups, unless this task is handled by +some other external system.

+
+
+
+

Option List

+
+

Logging & activation options

+

Script logging configuration and script activation

+ +
+
+

Backup policy options

+

These options configure the backup policy to apply

+ +
+
+

Encryption and signing options

+

These options configure how the script uses GPG to encrypt and sign the ttyrec files

+ +
+
+

Remote backup options

+

These options configure how the script should push the encrypted backups to a remote system

+ +
+
+
+

Option Reference

+
+

Logging & activation

+
+

LOGFILE

+
+
Type
+

string, path to a file

+
+
Default
+

""

+
+
+

File where the logs will be written to (don't forget to configure logrotate!). +Note that using this configuration option, the script will directly write to the file, without using syslog. +If empty, won't log directly to any file.

+
+
+

LOG_FACILITY

+
+
Type
+

string

+
+
Default
+

"local6"

+
+
+

The syslog facility to use for logging the script output. +If set to the empty string, we'll not log through syslog at all. +If this configuration option is missing from your config file altogether, +the default value will be used (local6), which means that we'll log to syslog.

+
+
+

ENABLED

+
+
Type
+

0 or 1

+
+
Default
+

1

+
+
+

If set to 1, the script is enabled and will run when started by crond.

+
+
+
+

Backup policy

+
+

DESTDIR

+
+
Type
+

path to a folder

+
+
Default
+

""

+
+
Example
+

"/root/backups"

+
+
+

Folder where to put the backup artefacts (.tar.gz files). +This folder will be created if needed. If empty or omitted, +the script won't run: this option is mandatory.

+
+
+

DAYSTOKEEP

+
+
Type
+

int > 0

+
+
Default
+

90

+
+
+

Number of days to keep the old backups on the filesystem before deleting them.

+
+
+
+

Encryption and signing

+
+

GPGKEYS

+
+
Type
+

string, space-separated list of GPG keys IDs

+
+
Default
+

""

+
+
Example
+

"41FDB9C7 DA97EFD1 339483FF"

+
+
+

List of public GPG keys to encrypt to (see gpg --list-keys), these must be separated by spaces. +Note that if this option is empty or omitted, backup artefacts will NOT be encrypted!

+
+
+

SIGNING_KEY

+
+
Type
+

string, GPG key ID in short or long format

+
+
Default
+

(none)

+
+
+

ID of the GPG key used to sign the ttyrec files. +The key must be in the local root keyring, check it with gpg --list-secret-keys. +If empty, the archives will not be signed, but encrypted only (using the GPGKEYS configuration above).

+
+
+

SIGNING_KEY_PASSPHRASE

+
+
Type
+

string

+
+
Default
+

(none)

+
+
+

This passphrase should be able to unlock the SIGNING_KEY defined above. +Please ensure this configuration file only readable by root (0640), to protect this passphrase. +As a security measure, the script will refuse to read the configuration otherwise.

+
+
+
+

Remote backup

+
+

PUSH_REMOTE

+
+
Type
+

string

+
+
Default
+

""

+
+
Example
+

"push@192.0.2.4:~/backup/"

+
+
+

The scp remote host push backups to. If empty or missing, won't push backups. +This will also be the case if the GPGKEYS option above is empty or missing, +because we will never push unencrypted backups. +Don't forget to put a trailing / (except if you want to push to the remote $HOME, +in which case ending with a simple : works, as per standard scp).

+
+
+

PUSH_OPTIONS

+
+
Type
+

string

+
+
Default
+

""

+
+
Example
+

"-i $HOME/.ssh/id_backup"

+
+
+

Additional options to pass to scp, if needed.

+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/administration/configuration/osh-cleanup-guest-key-access_conf.html b/administration/configuration/osh-cleanup-guest-key-access_conf.html new file mode 100644 index 0000000..a0fc35c --- /dev/null +++ b/administration/configuration/osh-cleanup-guest-key-access_conf.html @@ -0,0 +1,216 @@ + + + + + + + osh-cleanup-guest-key-access.conf — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

osh-cleanup-guest-key-access.conf

+
+
+

Note

+

This script is called by cron and is responsible for cleaning up dangling +accesses to group keys for group guests that no longer have access to any +server of the group. This happens when the last access a guest have on a +group has a TTL, and this TTL expires. +This is a basic background task of The Bastion, hence there is not much +to configure. You can still disable this script below, if needs be.

+
+
+
+

Option List

+
+

Logging & activation options

+

Script logging configuration and script activation

+ +
+
+
+

Option Reference

+
+

Logging & activation

+
+

syslog_facility

+
+
Type
+

string

+
+
Default
+

local6

+
+
+

The syslog facility to use for logging the script output. +If set to the empty string, we'll not log through syslog at all. +If this configuration option is missing from your config file altogether, +the default value will be used (local6), which means that we'll log to syslog.

+
+
+

enabled

+
+
Type
+

bool

+
+
Default
+

true

+
+
+

If not set to true (or a true value), the script will not run.

+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/administration/configuration/osh-encrypt-rsync_conf.html b/administration/configuration/osh-encrypt-rsync_conf.html new file mode 100644 index 0000000..066f15d --- /dev/null +++ b/administration/configuration/osh-encrypt-rsync_conf.html @@ -0,0 +1,441 @@ + + + + + + + osh-encrypt-rsync.conf — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

osh-encrypt-rsync.conf

+
+

Note

+

The osh-encrypt-rsync script is called by cron and is responsible for encrypting +and optionally pushing the recorded ttyrec files to a distant server, along +with the user logs (/home/*/*.log) and user sqlite files (/home/*/*.sqlite). +The global log and sqlite files are also handled (located in /home/logkeeper/). +Note that logs sent through syslog are NOT managed by this script.

+
+
+

Warning

+

If left unconfigured, this script won't do anything, and the recorded ttyrec files, +along with the log and sqlite files won't be encrypted or moved out from the server. +This might not be a problem for low-traffic bastions or if you have plenty of storage available, though.

+
+
+

Option List

+
+

Logging options

+

These options configure the way the script logs its actions

+ +
+
+

Encryption and signing options

+

These options configure how the script uses GPG to encrypt and sign the ttyrec files

+ +
+
+

Push files to a remote destination options

+

These options configure the way the script uses rsync to optionally push the encrypted files out of the server

+ +
+
+
+

Option Reference

+
+

Logging

+
+

logfile

+
+
Type
+

string, path to a file

+
+
Default
+

""

+
+
+

File where the logs will be written to (don't forget to configure logrotate!). +Note that using this configuration option, the script will directly write to the file, without using syslog. +If empty, won't log directly to any file.

+
+
+

syslog_facility

+
+
Type
+

string

+
+
Default
+

"local6"

+
+
+

The syslog facility to use for logging the script output. +If set to the empty string, we'll not log through syslog at all. +If this configuration option is missing from your config file altogether, +the default value will be used (local6), which means that we'll log to syslog.

+
+
+

verbose

+
+
Type
+

int >= 0

+
+
Default
+

0

+
+
+

The verbosity level of the logs produced by the script +0: normal (default) +1: log more information about what is happening +2: log debug-level information

+
+
+
+

Encryption and signing

+
+

signing_key

+
+
Type
+

string, GPG key ID in short or long format

+
+
Default
+

(none), setting a value is mandatory

+
+
+

ID of the GPG key used to sign the ttyrec files. +The key must be in the local root keyring, check it with gpg --list-secret-keys

+
+
+

signing_key_passphrase

+
+
Type
+

string

+
+
Default
+

(none), setting a value is mandatory

+
+
+

This passphrase should be able to unlock the signing_key defined above. +As a side note, please ensure this configuration file only readable by root (0640), +to protect this passphrase. As a security measure, +the script will refuse to read the configuration otherwise.

+
+
+

recipients

+
+
Type
+

array of array of strings, a string being a GPG key ID in short or long format

+
+
Default
+

(none), setting a value is mandatory

+
+
+

The ttyrecs will be encrypted with those GPG keys, possibly using multi-layer GPG encryption. +Each sub-array is a layer, the first sub-array being the first encryption layer (which is also the last one for decryption) +To completely decrypt a ttyrec, one would need at least one key of each layer. +To encrypt only to a single layer and to only one key, simply use [ [ "KEYID" ] ]. +To encrypt to a single layer but with 3 keys being able to decrypt the ttyrec, use [ [ "KEY1", "KEY2", "KEY3" ] ], etc. +A common use of multi-layer encryption is to have the first layer composed of the auditors' GPG keys, and +the second layer composed of the sysadmins' GPG keys. During an audit, the sysadmins would get the ttyrec encrypted file, +decrypt the second encryption layer (the first for decryption), and handle the now only auditor-protected file to the auditors. +All public keys must be in the local root keyring (gpg --list-keys). +Don't forget to trust those keys "ultimately" in root's keyring, too (gpg --edit-key ID)

+
+
+

encrypt_and_move_to_directory

+
+
Type
+

string, a valid directory name

+
+
Default
+

"/home/.encrypt"

+
+
+

After encryption (and compression), move ttyrec, user sqlite and user log files to subdirs of this directory. +It'll be created if it doesn't exist yet. +You may want this directory to be the mount point of a remote filer, if you wish. +If you change this, it's probably a good idea to ensure that the path is excluded from the +master/slave synchronization, in /etc/bastion/osh-sync-watcher.rsyncfilter. +This is already the case for the default value.

+
+
+

encrypt_and_move_ttyrec_delay_days

+
+
Type
+

int > 0, or -1

+
+
Default
+

14

+
+
+

Don't touch ttyrec files that have a modification time more recent than this amount of days. +The files won't be encrypted nor moved yet, and will still be readable by the selfPlaySession command. +You can set this to a (possibly) much higher value, the only limit is the amount of disk space you have. +If set to -1, the ttyrec files will never get encrypted or moved by this script. +The eligible files will be encrypted and moved to encrypt_and_move_to_directory. +NOTE: The old name of this option is encrypt_and_move_delay_days. +If it is found in your configuration file and encrypt_and_move_ttyrec_delay_days is not, +then the value of encrypt_and_move_delay_days will be used instead of the default.

+
+
+

encrypt_and_move_user_logs_delay_days

+
+
Type
+

int >= 31, or -1

+
+
Default
+

31

+
+
+

Don't touch user log files (/home/*/*.log) that have been modified more recently than this amount of days. +The bare minimum is 31 days, to ensure we're not moving a current-month file. +You can set this to a (possibly) much higher value, the only limit is the amount of disk space you have. +If set to -1, the user log files will never get encrypted or moved by this script. +The eligible files will be encrypted and moved to encrypt_and_move_to_directory.

+
+
+

encrypt_and_move_user_sqlites_delay_days

+
+
Type
+

int >= 31, or -1

+
+
Default
+

31

+
+
+

Don't touch user sqlite files (/home/*/*.sqlite) that have been modified more recently than this amount of days. +The files won't be encrypted nor moved yet, and will still be usable by the selfListSessions command. +The bare minimum is 31 days, to ensure we're not moving a current-month file. +You can set this to a (possibly) much higher value, the only limit is the amount of disk space you have. +If set to -1, the user sqlite files will never get encrypted or moved by this script. +The eligible files will be encrypted and moved to encrypt_and_move_to_directory.

+
+
+
+

Push files to a remote destination

+
+

rsync_destination

+
+
Type
+

string

+
+
Default
+

""

+
+
Example
+

"user@remotebackup.example.org:/remote/dir"

+
+
+

The value of this option will be passed to rsync as the destination. +Note that the source of the rsync is already configured above, as the encrypt_and_move_to_directory. +We only rsync the files that have already been encrypted and moved there. +If this option is empty, this will disable rsync, meaning that the ttyrec files will be encrypted, +but not moved out of the server. In other words, the files will pile up in encrypt_and_move_to_directory, +which can be pretty okay in you have enough disk space.

+
+
+

rsync_rsh

+
+
Type
+

string

+
+
Default
+

""

+
+
Example
+

"ssh -p 222 -i /root/.ssh/id_ed25519_backup"

+
+
+

The value of this option will be passed to rsync's --rsh option. +This is useful to specify an SSH key or an alternate SSH port for example. +This option is ignored when rsync is disabled (i.e. when rsync_destination is empty).

+
+
+

rsync_delay_before_remove_days

+
+
Type
+

int >= 0, or -1

+
+
Default
+

0

+
+
+

After encryption/compression, and successful rsync of encrypt_and_move_to_directory to remote, +wait for this amount of days before removing the encrypted/compressed files locally. +Specify 0 to remove the files as soon as they're transferred. +This option is ignored when rsync is disabled (i.e. when rsync_destination is empty). +Note that if rsync is enabled (see rsync_destination above), we'll always sync the files present in +encrypt_and_move_to_directory as soon as we can, to ensure limitation of logs data loss in case of +catastrophic failure of the server. The rsync_delay_before_remove_days option configures the number +of days after we remove the files locally, but note that these have already been transferred remotely +as soon as they were present in encrypt_and_move_to_directory. +To rsync the files remotely but never delete them locally, set this to -1.

+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/administration/configuration/osh-http-proxy_conf.html b/administration/configuration/osh-http-proxy_conf.html new file mode 100644 index 0000000..618dfe4 --- /dev/null +++ b/administration/configuration/osh-http-proxy_conf.html @@ -0,0 +1,377 @@ + + + + + + + osh-http-proxy.conf — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

osh-http-proxy.conf

+
+
+

Note

+

This module is optional, and disabled by default. +To know more about the HTTP Proxy feature of The Bastion, +please check the HTTPS Proxy section

+
+
+
+

Option List

+
+

HTTP Proxy configuration options

+

These options modify the behavior of the HTTP Proxy, an optional module of The Bastion

+ +
+
+
+

Option Reference

+
+

HTTP Proxy configuration

+
+

enabled

+
+
Type
+

bool

+
+
Default
+

false

+
+
+

Whether the HTTP proxy daemon daemon is enabled or not. If it's not enabled, it'll exit when started. +Of course, if you want to enable this daemon, you should also configure your init system to start it +for you. Both sysV-style scripts and systemd unit files are provided. +For systemd, using systemctl enable osh-http-proxy.service should be enough. +For sysV-style inits, it depends on the scripts provided for your distro, +but usually update-rc.d osh-http-proxy defaults then update-rc.d osh-http-proxy enable should +do the trick.

+
+
+

port

+
+
Type
+

int, 1 to 65535

+
+
Default
+

8443

+
+
+

The port to listen to. You can use ports < 1024, in which case privileges will be dropped after binding, +but please ensure your systemd unit file starts the daemon as root in that case.

+
+
+

ssl_certificate

+
+
Type
+

string

+
+
Default
+

/etc/ssl/certs/ssl-cert-snakeoil.pem

+
+
+

The file that contains the server SSL certificate in PEM format. +For tests, install the ssl-cert package and point this configuration item +to the snakeoil certs (which is the default).

+
+
+

ssl_key

+
+
Type
+

string

+
+
Default
+

/etc/ssl/private/ssl-cert-snakeoil.key

+
+
+

The file that contains the server SSL key in PEM format. +For tests, install the ssl-cert package and point this configuration item +to the snakeoil certs (which is the default).

+
+
+

ciphers

+
+
Type
+

string

+
+
Default
+

""

+
+
Example
+

"ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256"

+
+
+

The ordered list the TLS server ciphers, in openssl classic format. Use openssl ciphers +to see what your system supports, an empty list leaves the choice to your openssl libraries default +values (system-dependent)

+
+
+

insecure

+
+
Type
+

bool

+
+
Default
+

false

+
+
+

Whether to ignore SSL certificate verification for the connection between the bastion and the devices

+
+
+

min_servers

+
+
Type
+

int, 1 to 512

+
+
Default
+

8

+
+
+

Number of child processes to start at launch

+
+
+

max_servers

+
+
Type
+

int, 1 to 512

+
+
Default
+

32

+
+
+

Hard maximum number of child processes that can be active at any given time no matter what

+
+
+

min_spare_servers

+
+
Type
+

int, 1 to 512

+
+
Default
+

8

+
+
+

The daemon will ensure that there is at least this number of children idle & ready to accept +new connections (as long as max_servers is not reached)

+
+
+

max_spare_servers

+
+
Type
+

int, 1 to 512

+
+
Default
+

16

+
+
+

The daemon will kill idle children to keep their number below this maximum when traffic is low

+
+
+

timeout

+
+
Type
+

int, 1 to 3600

+
+
Default
+

120

+
+
+

Timeout delay (in seconds) for the connection between the bastion and the devices

+
+
+

log_request_response

+
+
Type
+

bool

+
+
Default
+

true

+
+
+

When enabled, the complete response of the device to the request we forwarded will be logged, +otherwise we'll only log the response headers

+
+
+

log_request_response_max_size

+
+
Type
+

int, 0 to 2^30 (1 GiB)

+
+
Default
+

65536

+
+
+

This option only applies when log_request_response is true (see above). +When set to zero, the complete response will be logged in the account's home log directory, +including the body, regardless of its size. If set to a positive integer, +the query response will only be partially logged, with full status and headers but the body only up +to the specified size. This is a way to avoid turning off request response logging completely on +very busy bastions, by ensuring logs growth don't get out of hand, as some responses to queries can +take megabytes, with possibly limited added value to traceability.

+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/administration/configuration/osh-lingering-sessions-reaper_conf.html b/administration/configuration/osh-lingering-sessions-reaper_conf.html new file mode 100644 index 0000000..c50d1a0 --- /dev/null +++ b/administration/configuration/osh-lingering-sessions-reaper_conf.html @@ -0,0 +1,252 @@ + + + + + + + osh-lingering-sessions-reaper.conf — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

osh-lingering-sessions-reaper.conf

+
+
+

Note

+

This script is called by cron and is responsible for terminating +lingering sessions that no longer have any tty attached nor parent PID, +and have been running for some time.

+
+
+
+

Option List

+
+

Logging & activation options

+

Script logging configuration and script activation

+ +
+
+

Main options

+

These options govern the behavior of the script

+ +
+
+
+

Option Reference

+
+

Logging & activation

+
+

LOGFILE

+
+
Type
+

string, path to a file

+
+
Default
+

""

+
+
+

File where the logs will be written to (don't forget to configure logrotate!). +Note that using this configuration option, the script will directly write to the file, without using syslog. +If empty, won't log directly to any file.

+
+
+

LOG_FACILITY

+
+
Type
+

string

+
+
Default
+

"local6"

+
+
+

The syslog facility to use for logging the script output. +If set to the empty string, we'll not log through syslog at all. +If this configuration option is missing from your config file altogether, +the default value will be used (local6), which means that we'll log to syslog.

+
+
+

ENABLED

+
+
Type
+

0 or 1

+
+
Default
+

1

+
+
+

If set to 1, the script is enabled and will run when started by crond.

+
+
+
+

Main

+
+

MAX_AGE

+
+
Type
+

int >= 0

+
+
Default
+

86400

+
+
+

The minimum number of seconds a session must have been opened before +being considered as possibly a lingering orphan session. +Still alive sessions, even older than MAX_AGE seconds, will be kept.

+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/administration/configuration/osh-orphaned-homedir_conf.html b/administration/configuration/osh-orphaned-homedir_conf.html new file mode 100644 index 0000000..fcbab78 --- /dev/null +++ b/administration/configuration/osh-orphaned-homedir_conf.html @@ -0,0 +1,230 @@ + + + + + + + osh-orphaned-homedir.conf — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

osh-orphaned-homedir.conf

+
+
+

Note

+

This script is called by cron and is responsible for clearing up +orphaned home directories on secondary bastions. +Indeed, once the user has been deleted, a few files may remain, +such as logs, so this script handles the proper archiving +of these sparse files, before removing the orphaned home directory.

+
+
+
+

Option List

+
+

Logging & activation options

+

Script logging configuration and script activation

+ +
+
+
+

Option Reference

+
+

Logging & activation

+
+

LOGFILE

+
+
Type
+

string, path to a file

+
+
Default
+

""

+
+
+

File where the logs will be written to (don't forget to configure logrotate!). +Note that using this configuration option, the script will directly write to the file, without using syslog. +If empty, won't log directly to any file.

+
+
+

LOG_FACILITY

+
+
Type
+

string

+
+
Default
+

"local6"

+
+
+

The syslog facility to use for logging the script output. +If set to the empty string, we'll not log through syslog at all. +If this configuration option is missing from your config file altogether, +the default value will be used (local6), which means that we'll log to syslog.

+
+
+

ENABLED

+
+
Type
+

0 or 1

+
+
Default
+

1

+
+
+

If set to 1, the script is enabled and will run when started by crond.

+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/administration/configuration/osh-piv-grace-reaper_conf.html b/administration/configuration/osh-piv-grace-reaper_conf.html new file mode 100644 index 0000000..ad752c0 --- /dev/null +++ b/administration/configuration/osh-piv-grace-reaper_conf.html @@ -0,0 +1,213 @@ + + + + + + + osh-piv-grace-reaper.conf — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

osh-piv-grace-reaper.conf

+
+
+

Note

+

This script is called by cron and is responsible for removing temporary +grace periods on PIV policies, once they expire. If you don't use PIV keys, +this script won't do anything (see PIV keys support).

+
+
+
+

Option List

+
+

Logging & activation options

+

Script logging configuration and script activation

+ +
+
+
+

Option Reference

+
+

Logging & activation

+
+

syslog_facility

+
+
Type
+

string

+
+
Default
+

local6

+
+
+

The syslog facility to use for logging the script output. +If set to the empty string, we'll not log through syslog at all. +If this configuration option is missing from your config file altogether, +the default value will be used (local6), which means that we'll log to syslog.

+
+
+

enabled

+
+
Type
+

bool

+
+
Default
+

true

+
+
+

If not set to true (or a true value), the script will not run.

+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/administration/configuration/osh-remove-empty-folders_conf.html b/administration/configuration/osh-remove-empty-folders_conf.html new file mode 100644 index 0000000..262ab80 --- /dev/null +++ b/administration/configuration/osh-remove-empty-folders_conf.html @@ -0,0 +1,255 @@ + + + + + + + osh-remove-empty-folders.conf — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

osh-remove-empty-folders.conf

+
+
+

Note

+

This script is called by cron and is responsible for getting rid of empty +folders in the ttyrec/ directory of users homes, which may contain a +high amount of empty folders for busy users connecting to a lot of +different servers, as we create one folder per destination IP. +Of course, this script will only remove empty folders, never actual files.

+
+
+
+

Option List

+
+

Logging & activation options

+

Script logging configuration and script activation

+ +
+
+

Behavior options

+

These options govern the behavior of the script

+ +
+
+
+

Option Reference

+
+

Logging & activation

+
+

LOGFILE

+
+
Type
+

string, path to a file

+
+
Default
+

""

+
+
+

File where the logs will be written to (don't forget to configure logrotate!). +Note that using this configuration option, the script will directly write to the file, without using syslog. +If empty, won't log directly to any file.

+
+
+

LOG_FACILITY

+
+
Type
+

string

+
+
Default
+

"local6"

+
+
+

The syslog facility to use for logging the script output. +If set to the empty string, we'll not log through syslog at all. +If this configuration option is missing from your config file altogether, +the default value will be used (local6), which means that we'll log to syslog.

+
+
+
+

Behavior

+
+

ENABLED

+
+
Type
+

0 or 1

+
+
Default
+

1

+
+
+

If set to 1, the script is enabled and will attempt to garbage-collect empty directories located +in /home/*/ttyrec. If set to anything else, the script is considered disabled and will not run.

+
+
+

MTIME_DAYS

+
+
Type
+

int, >= 0

+
+
Default
+

1

+
+
+

The amount of days the empty folder must have been empty before considering a removal. You probably +don't need to change the default value, unless you want to ensure that a given folder has not been +used since some time before removing it (this has no impact as folders are re-created as needed).

+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/administration/configuration/osh-sync-watcher_sh.html b/administration/configuration/osh-sync-watcher_sh.html new file mode 100644 index 0000000..5ff157f --- /dev/null +++ b/administration/configuration/osh-sync-watcher_sh.html @@ -0,0 +1,301 @@ + + + + + + + osh-sync-watcher.sh — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

osh-sync-watcher.sh

+
+
+

Note

+

This daemon is responsible for ensuring secondary bastions +are synced up to their primary at all times. +If you don't have such HA setup, you can ignore this config file. +For more information, refer to +Clustering (High Availability).

+
+
+
+

Option List

+
+

Logging options

+

These options configure the way the script logs its actions

+ +
+
+

Daemon setup options

+

These options configure whether the synchronization daemon is enabled

+ +
+
+

Remote synchronization options

+

These options configure how the primary bastion should push its configuration to the secondaries

+ +
+
+
+

Option Reference

+
+

Logging

+
+

logdir

+
+
Type
+

string

+
+
Default
+

""

+
+
+

Directory where the logs will be written to. Note that using this configuration option, the script will directly write to a file, without using syslog. If empty, won't log directly to a file.

+
+
+

syslog

+
+
Type
+

string

+
+
Default
+

"local6"

+
+
+

The syslog facility to use for logging the script output. If set to the empty string, we'll not log through syslog at all. If this configuration option is missing from your config file altogether, the default value will be used (local6), which means that we'll log to syslog.

+
+
+
+

Daemon setup

+
+

enabled

+
+
Type
+

int

+
+
Default
+

0

+
+
+

If set to anything else than 1, the daemon will refuse to start (e.g. you don't have secondary bastions). You can set this to 1 when you've configured and tested the primary/secondaries setup.

+
+
+

timeout

+
+
Type
+

int > 0

+
+
Default
+

120

+
+
+

The maximum delay, in seconds, after which we'll forcefully synchronize our data to the secondaries, even if no change was detected.

+
+
+
+

Remote synchronization

+
+

rshcmd

+
+
Type
+

string

+
+
Default
+

""

+
+
Example
+

"ssh -q -i /root/.ssh/id_master2slave -o StrictHostKeyChecking=accept-new"

+
+
+

This value will be passed as the --rsh parameter of rsync (don't use -p to specify the port here, use the remotehostlist config below instead), this can be used to specify which SSH key to use, for example. NOTE THAT THIS OPTION IS MANDATORY (if you don't have anything to specify here, you can just say ssh). If you followed the standard installation procedure, the "example" value specified below will work.

+
+
+

remoteuser

+
+
Type
+

string

+
+
Default
+

"bastionsync"

+
+
+

The remote user to connect as, using ssh while rsyncing to secondaries. You probably don't need to change this.

+
+
+

remotehostlist

+
+
Type
+

space-separated list of strings, each string being either 'ip' or 'ip:port'

+
+
Default
+

""

+
+
Example
+

"192.0.2.17 192.0.2.12:2244"

+
+
+

The list of the secondary bastions to push our data to. If this list is empty, the daemon won't do anything.

+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/administration/logs.html b/administration/logs.html new file mode 100644 index 0000000..b45324e --- /dev/null +++ b/administration/logs.html @@ -0,0 +1,694 @@ + + + + + + + Logs — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Logs

+
+

Note

+

The Bastion comes with a lot of traceability features, you have to ensure that you've done your configuration +correctly so that those logs are kept in a safe place when you need them. It is warmly advised to enable at least +the syslog option, and push your logs to a remote syslog server.

+
+ +
+

Message types

+

The Bastion has several configurable ways of logging events, but before detailing those, +let's see the different message types that can be logged. +The Bastion currently has 12 different message types, listed below:

+ +

First, let's list the fields that are common to all the message types:

+
+
uniqid

This is the unique connection ID, you can find all the logs relevant to the same connection +by filtering on the uniqid. This ID is also, by default, part of the filename given to the ttyrec files, +for easier correlation. The same ID is also used in the sqlite logs, if you enabled those. In some rare cases, +the value can be "-", for example if a satellite script has something to log, +not linked to an actual connection or session.

+
+
version

This indicates the version of The Bastion software that is writing the log

+
+
pid, ppid

This is the system PID (resp. system parent PID) of the process writing the log, +for easier correlation with system audit logs if you have them

+
+
sysuser

This is the system user under which the process writing the log is currently running on, +can be useful to detect abnormalities

+
+
sudo_user

When the value is present, it contains the system user name that has launched the sudo command the code is +currently running under (this will be the case if a so-called "bastion helper" is pushing a log, for example). +However this field will often have an empty value, it means that the code that is writing the log +is not running under sudo

+
+
uid, gid

This is the system user ID aka UID (resp. group ID aka GID) under which +the process writing the log is currently running

+
+
account

This is the name of the bastion account that launched the command that produced the log

+
+
+

The other fields depend on the message type, as detailed in the next sections.

+
+

open

+

This log is produced when a user established a session with the bastion.

+

Example:

+
Dec 28 11:12:26 myhostname bastion: open uniqid="e9e4baf6873b" version="3.01.03" pid="18721" ppid="18720"
+sysuser="gthreepw" sudo_user="" uid="99998" gid="99998" account="gthreepw" cmdtype="ssh" allowed="true"
+ip_from="172.17.0.1" port_from="39696" host_from="172.17.0.1" ip_bastion="172.17.0.2" port_bastion="22"
+host_bastion="myhostname.example.org" user="foo" ip_to="172.17.0.123" port_to="22" host_to="srv123.example.org"
+plugin="" globalsql="ok" accountsql="ok" comment="" params="ttyrec -f
+/home/gthreepw/ttyrec/172.17.0.123/2020-12-28.11-12-26.074894.e9e4baf6873b.gthreepw.foo.172.17.0.123.22.ttyrec -F
+/home/gthreepw/ttyrec/172.17.0.123/%Y--%d.%H-%M-%S.#usec#.e9e4baf6873b.gthreepw.foo.172.17.0.123.22.ttyrec --
+/usr/bin/ssh 172.17.0.123 -l foo -p 22 -i /home/gthreepw/.ssh/id_rsa4096_private.1594384739 -i
+/home/keykeeper/keyagroup/id_ed25519_agroup.1607524914 -o PreferredAuthentications=publickey"
+
+
+

Fields:

+
+
cmdtype

Indicates which category of command has been requested by the user:

+
    +

  • ssh: the user is trying to establish an SSH egress connection to a remote server

    • +

  • telnet: the user is trying to establish a telnet egress connection to a remote server

    • +

  • abort: the action requested by the user has been aborted early, possibly because of permission issues +or impossibility to understand the request, more information is available in the bastion_comment field

    • +

  • osh: the user is trying to execute a bastion plugin with the --osh command

    • +

  • interactive: the user just entered interactive mode. Note that all the commands launched through +the interactive mode will still have their own log.

    • +

  • sshas: an administrator is currently establishing a connection on behalf of another user. +This connection will also have its own log.

    • +

  • proxyhttp_daemon: the HTTPS proxy daemon received a request

    • +

  • proxyhttp_worker: the HTTPS proxy worker specifically spawned for the user by the daemon is handling the request

    • +
+
+
allowed

Indicates whether the requested action was allowed or not by the bastion, after executing the authorization phase. +Will be either "true" or "false".

+
+
ip_from, port_from, host_from

These are the IP and source port as seen by the bastion, from which the ingress connection originates. +If the bastion can resolve the reverse of the IP to a hostname, it'll be indicated in host_from, +otherwise the IP will be repeated there.

+
+
ip_bastion, port_bastion, host_bastion

These are the IP and port of the bastion to which the ingress connection terminates. +If your bastion has several IPs and/or interfaces, this can be useful. +If the bastion can resolve the reverse of the IP to a hostname, it'll be indicated in host_bastion, +otherwise the IP will be repeated there.

+
+
ip_to, port_to, host_to

These are the IP and destination port to which the bastion will connect on the egress side, +on behalf of the requesting user. If the bastion can resolve the reverse of the IP to a hostname, +it'll be indicated in host_to, otherwise the IP will be repeated there.

+
+
plugin

When cmdtype is osh, the name of the command (or plugin) will appear in this field. +Otherwise it'll be blank.

+
+
accountsql

This field will contain either:

+
    +

  • ok: when enableAccountSqlLog is enabled, and we successfully inserted a new row for the log

    • +

  • no: when enableAccountSqlLog is disabled

    • +

  • error: when we couldn't insert a new row, error followed by a detailed error message, +for example "error SQL error [global] err 8 while doing [inserting data (execute)]: +attempt to write a readonly database".

    • +
+
+
globalsql

This field can contain the same values than accountsql above, +but for enableGlobalSqlLog instead of enableAccountSqlLog

+
+
comment

Some more information about the current event, depending on the cmdtype value.

+
+
params

This is the fully expanded command line that will be launched under the currently running user rights, +to establish the egress connection, if applicable.

+
+
+
+
+

close

+

This log is produced when a user terminates a currently running session with The Bastion. +It is always matched (through the uniqid) to another log with the open message type.

+

Example:

+
Dec 28 11:12:26 myhostname bastion: open uniqid="e9e4baf6873b" version="3.01.03" pid="18721" ppid="18720"
+sysuser="gthreepw" sudo_user="" uid="99998" gid="99998" account="gthreepw" cmdtype="ssh" allowed="true"
+ip_from="172.17.0.1" port_from="39696" host_from="172.17.0.1" ip_bastion="172.17.0.2" port_bastion="22"
+host_bastion="myhostname.example.org" user="foo" ip_to="172.17.0.123" port_to="22"
+host_to="srv123.example.org" plugin="" globalsql="ok" accountsql="ok" comment="" params="ttyrec -f
+/home/gthreepw/ttyrec/172.17.0.123/2020-12-28.11-12-26.074894.e9e4baf6873b.gthreepw.foo.172.17.0.123.22.ttyrec -F
+/home/gthreepw/ttyrec/172.17.0.123/%Y--%d.%H-%M-%S.#usec#.e9e4baf6873b.gthreepw.foo.172.17.0.123.22.ttyrec --
+/usr/bin/ssh 172.17.0.123 -l foo -p 22 -i /home/gthreepw/.ssh/id_rsa4096_private.1594384739 -i
+/home/keykeeper/keyagroup/id_ed25519_agroup.1607524914 -o PreferredAuthentications=publickey" sysret="0"
+signal="" comment_close="hostkey_changed passauth_disabled" duration="43.692"
+
+
+

All the fields from the corresponding open log are repeated in this log line, in addition to the following fields:

+
+
sysret

Return code of the launched system command (that established the egress connection) +or the plugin (if an --osh command was passed). +If we don't have a return code, for example because we were interrupted by a signal, the value will be empty.

+
+
signal

Name of the UNIX signal that terminated the command, if any. For example "HUP" or "SEGV". +If we got no signal, the value will be empty.

+
+
comment_close

A space-separated list of messages giving some hints gathered at the end of a session. +For example hostkey_changed passauth_disabled means that we detected that our egress ssh client +emitted a warning telling us that the remote keys changed, and also that password authentication has been disabled.

+
+
duration

Amount of seconds (with a millisecond precision) between the session open and the session close.

+
+
+
+
+

warn, die

+

These logs are produced when Perl emits a warning (using the warn() call), +or respectively when Perl halts abruptly due to a die() call. +This should not happen during nominal use. You might want to keep a look on those messages if they're produced.

+

Example:

+
Dec 28 11:12:26 myhostname bastion: warn uniqid="a46e51b5dce4" version="3.01.02" pid="3308212" ppid="3308206"
+sysuser="lechuck" sudo_user="" uid="99994" gid="99994" msg="Cannot find termcap: TERM not set at
+/usr/share/perl/5.28/Term/ReadLine.pm line 379.  " program="/opt/bastion/bin/shell/osh.pl" cmdline="-c^-i ssh
+root@172.17.0.222 id" trace=" at /opt/bastion/bin/shell/../../lib/perl/OVH/Bastion.pm
+line 41.   OVH::Bastion::__ANON__(\"Cannot find termcap: TERM not set at /usr/share/perl/5.28/Ter\"...)
+called at /usr/share/perl/5.28/Term/ReadLine.pm line
+391     Term::ReadLine::TermCap::ornaments(Term::ReadLine::Stub=ARRAY(0x5575da36b690), 1) called at
+/opt/bastion/lib/perl/OVH/Bastion/interactive.inc line 77   OVH::Bastion::interactive(\"realOptions\", \"-i ssh
+root\\@172.17.0.222 id\"..., \"timeoutHandler\", CODE(0x5575da15aa78), \"self\", \"lechuck\")
+called at /opt/bastion/bin/shell/osh.pl line 485 "
+
+
+

Fields:

+
+
msg

This is the message used as a parameter to the warn() or die() call

+
+
program

Contains the name of the currently running program (first parameter of execve())

+
+
cmdline

Contains the full command line passed to the currently running program (remaining parameters of execve()). +The command-line fields are separated by ^'s.

+
+
trace

The call trace leading to this warn() or die()

+
+
+
+
+

warn-info, die-info

+

These logs are produced when some known portion of code (including libraries) called warn() or die() +but in a known case that can happen during nominal use. +Don't use these logs to directly trigger an alert, but you can keep an eye on those, as e.g. an unusually +high number of occurences in a short time may be a weak signal that somebody or something is misbehaving.

+

The fields are the same than the ones specified above for warn and die.

+
+
+

code-info

+

These logs are produced when some portion of the code encounters an minor issue that is worth logging, +to e.g. help debugging an issue or understanding what happened in a specific use-case, +for example if a user-session ended abruptly. +These logs are not the result of an error on the bastion configuration and don't mandate immediate admin attention.

+

Example:

+
Dec 25 14:56:11 myhostname bastion: code-info uniqid="98d2f32b1a2d" version="3.07.00" pid="3708843"
+ppid="3708842" sysuser="lechuck" sudo_user="" uid="8423" gid="8423" msg="execute():
+error while syswriting(Broken pipe) on stderr, aborting this cycle"
+
+
+

Fields:

+
+
msg

A human-readable text describing the error

+
+
+
+
+

code-warning

+

These logs are produced when some portion of the code encounters an unexpected issue or abnormality +that is worth logging. They'll usually not be emitted due to a bad user interaction, but rather if the bastion +is misconfigured, or for anything that might need some attention or fixing from the admins.

+

Example:

+
Dec 28 11:12:26 myhostname bastion: code-warning uniqid="ffee33abd1ba" version="3.01.03" pid="3709643"
+ppid="3709642" sysuser="lechuck" sudo_user="" uid="8423" gid="8423" msg="Configuration error
+for plugin selfGenerateEgressKey on the 'disabled' key: expected a boolean, casted 'no' into false"
+
+
+

Fields:

+
+
msg

A human-readable text describing the error

+
+
+
+
+

acl

+

This log is produced when an access control list is modified, +either personal accesses of an account, or a group servers list.

+

Example:

+
Dec 28 11:12:26 myhostname bastion: acl uniqid="f25fe71c6635" version="3.01.02" pid="3116604"
+ppid="3116603" sysuser="keysomegroup" sudo_user="lechuck" uid="10006" gid="10057" action="add"
+type="group" group="somegroup" account="" user="root" ip="172.16.2.2" port="22" ttl="" force_key="" comment=""
+
+
+

Fields:

+
+
action

Will be either add if an access is added, or del if an access is removed

+
+
type

Will be either group if we're modifying a group server list, in which case the group field will be filled, +or account if we're modifying personal accesses of an account, in which case the account field will be filled

+
+
group

If type is group, indicates which group servers list has been modified

+
+
account

If type is account, indicates which account personal accesses have been modified

+
+
user

The remote user part of the access we're adding/removing

+
+
ip

The IP or IP block of the access we're adding/removing

+
+
port

The port of the access we're adding/removing

+
+
ttl

If set, represents the TTL after which the access will automatically be removed

+
+
force_key

If set, this contains the fingerprint of the key that'll be used for this access

+
+
comment

Any comment set by the user adding/removing the access

+
+
+
+
+

membership

+

This log is produced when one of a group's role list is modified: +either an owner, member, guest, aclkeeper or gatekeeper.

+

Example:

+
Dec 28 11:12:26 myhostname bastion: membership uniqid="a00993ec6767" version="3.01.02"
+pid="1072528" ppid="1072497" sysuser="lechuck" sudo_user="" uid="2070" gid="2070" action="add"
+type="member" group="monkeys" account="stan" self="lechuck" user="" host="" port="" ttl=""
+
+
+

Fields:

+
+
action

Either add when an account is added to a group role list, or del when an account is removed

+
+
type

Type of the role list we're modifying, either member, aclkeeper, gatekeeper, guest or owner

+
+
group

Group whose one of the role list is being modified

+
+
account

Account being added/removed to/from the group role list

+
+
self

Account performing the change

+
+
user

When type is guest, the remote user part of the access we're adding/removing

+
+
host

When type is guest, the IP or IP block part of the access we're adding/removing

+
+
port

When type is guest, the port of the access we're adding/removing

+
+
ttl

When type is guest and action is add, if a TTL has been specified for the access, it appears here

+
+
+
+
+

security

+

This log is produced when an important security event has occurred, such as when an admin impersonates another user, +or when a super owner uses his implicit global ownership to modify a group. You might want to watch those closely.

+

Example:

+
Dec 28 11:12:26 myhostname bastion: security uniqid="601a17b5e5ba" version="3.01.03" pid="20519"
+ppid="20518" sysuser="lechuck" sudo_user="" uid="2604" gid="2604" type="admin-ssh-as" account="lechuck"
+sudo-as="gthreepw" plugin="ssh" params="--user root --host supersecretserver.example.org --port 22"
+
+
+

Fields:

+
+
type

Type of the security event that occurred. Can be:

+
    +

  • admin-ssh-as: an admin impersonated another user to establish an egress connection

    • +

  • admin-sudo: an admin impersonated another user and launched an osh plugin on their behalf

    • +

  • superowner-override: a super owner used his implicit ownership on all groups to modify a group

    • +
+
+
account

Account that emitted the security event

+
+
sudo-as

When type is admin-ssh-as or admin-sudo, name of the account that was impersonated

+
+
plugin

Name of the osh plugin that was launched

+
+
params

Parameters passed to the plugin, or command line used to establish the egress connection

+
+
+
+
+

group

+

This log is produced when a group is created or deleted. +Note that membership modifications are referenced with the membership type instead, see above.

+

Example:

+
Dec 28 11:12:26 myhostname bastion: group uniqid="56f321fb3e58" version="3.01.03" pid="1325901"
+ppid="1325900" sysuser="root" sudo_user="lechuck" uid="0" gid="0" action="create" group="themonkeys"
+owner="stan" egress_ssh_key_algorithm="ed25519" egress_ssh_key_size="256" egress_ssh_key_encrypted="false"
+
+
+

Fields:

+
+
action

Either create or delete, indicating whether the group has just been created or deleted

+
+
group

The group name being created or deleted

+
+
owner

When action is create, the name of the owner of the new group we're creating

+
+
egress_ssh_key_algorithm, egress_ssh_key_size

When action is create, the algorithm (and size) used to generate the first pair of SSH keys, +can be empty if --no-key was specified

+
+
egress_ssh_key_encrypted

When action is create, if a key was generated, +will be true if --encrypted has been used, false otherwise

+
+
+
+
+

account

+

This log is produced when an account is created or deleted.

+

Example:

+
Dec 21 14:30:26 myhostname bastion: account uniqid="ee4c91000b75" version="3.01.02" pid="537253" ppid="537252"
+sysuser="root" sudo_user="lechuck" uid="0" gid="0" action="create" account="stan" account_uid="8431"
+public_key="ssh-rsa AAAAB[...]" always_active="false" uid_auto="false" osh_only="false" immutable_key="false"
+comment="CREATED_BY=lechuck BASTION_VERSION=3.01.02 CREATION_TIME=Mon Dec 21 14:30:26 2020
+CREATION_TIMESTAMP=1608561026 COMMENT=requested_by_the_sword_master_of_melee_island_see_ticket_no_1337"
+
+
+

Fields:

+
+
action

Either create or delete, indicating whether the account has just been created or deleted

+
+
account

The account name being created or deleted

+
+
account_uid

When action is create, the UID associated corresponding to the account we're creating

+
+
public_key

When action is create, the public key we've generated for the new account

+
+
always_active, uid_auto, osh_only, immutable_key

When action is create, true if the corresponding option was specified (--always-active, +--uid-auto, --osh-only or --immutable-key), false otherwise

+
+
comment

When action is create, the comment specified at creation if any, with some metadata that'll be stored in +the account properties (created_by, bastion_version, creation_time, creation_timestamp)

+
+
tty_group

When action is delete, the name of the tty group specific to this account that was deleted at the same time

+
+
+
+
+
+

Syslog

+
+

Files location

+

If you use syslog-ng and installed the provided templates (which is the default if you used +the --new-install option to the install script), you'll have 4 files in your system log directory:

+
+
/var/log/bastion/bastion.log

This is where all the bastion usage logs will be written. All the above message types can be found in this file.

+
+
/var/log/bastion/bastion-die.log

This is where Perl crashes will be logged, with the message type die. +On a production bastion, this file should normally be empty.

+
+
/var/log/bastion/bastion-warn.log

This is where Perl warnings will be logged, with the message type warning. +On a production bastion, this file should mostly be empty.

+
+
/var/log/bastion/bastion-scripts.log

This is where all the satellite scripts (mostly found in the bin/cron/ directory) will log their output.

+
+
+
+
+

Log format

+

A syslog message will always match the following generic format:

+
SYSLOG_TIME SYSLOG_HOST bastion: MSGTYPE field1="value1" field2="second value" ...
+
+
+

Where SYSLOG_TIME is the usual datetime field added by your local syslog daemon, +and SYSLOG_HOST the hostname of the local machine. +The MSGTYPE indicates the message type of the log line (the list of types is further below). +Then, a possibly long list of fields with quoted values, depending on the MSGTYPE.

+

An example follows:

+
Dec 28 11:14:23 myhostname bastion: code-warning uniqid="e192fce7553a" version="3.01.03"
+pid="18803" ppid="18802" sysuser="gthreepw" sudo_user="" uid="99998" gid="99998"
+msg="Configuration error: specified adminAccounts 'joe' is not a valid account, ignoring"
+
+
+

In that case, the MSGTYPE is code-warning, and we have a few field/value couples with some metadata of interest, +followed by a human-readable message, indicated by the msg field.

+

Only satellite scripts will miss the field/value construction, which will just be replaced by a plain text message. +These logs are stored in /var/log/bastion/bastion-scripts.log by default.

+
+
+
+

Access logs

+

If you don't or can't use Syslog, the bastion can create and use access log files on its own, +without relying on a syslog daemon. Note that you can enable both syslog and these access logs, if you want.

+

These access logs will only contain open and close log types, which can be seen as "access logs". +All the other log types, such as warn, die, membership, etc. are only logged through syslog.

+

These logs are enabled through the enableGlobalAccessLog and enableAccountAccessLog options.

+
+
enableGlobalAccessLog

When enabled, a single log file will be used, located in /home/logkeeper/global-log-YYYYMM.log. +There will be one file per month. Note that it can grow quite large if you have a busy bastion.

+
+
enableAccountAccessLog

When enabled, one log file per account will be used, located in /home/USER/USER-log-YYYYMM.log. +There will be one file per month.

+
+
+

If both options are enabled, it means that every access log will be logged twice, to two different locations. +If you also enabled syslog, it's even three times!

+
+
+

SQLite logs

+

If you want to store access logs into local sqlite databases, you can enable either enableGlobalSqlLog, +enableAccountSqlLog, or both.

+
+
enableGlobalSqlLog

When enabled, a global sqlite database will be created in /home/logkeeper/global-log-YYYYMM.sqlite. +It'll contain one row per access (created at the same time the open log is emitted). +The following columns exist: id, timestamp, account, cmdtype, allowed, ipfrom, ipto, portto, user, plugin, uniqid. +Refer to the open log description to get the meaning of each column.

+
+
enableAccountSqlLog

When enabled, an sqlite database per account will be created in /home/USER/USER-log-YYYYMM.sqlite. +It'll contain one row per access (created at the same time the open log is emitted), +and the same row will be updated by the close event when it is emitted. The following columns exist: +id, timestamp, timestampusec, account, cmdtype, allowed, hostfrom, ipfrom, bastionip, bastionport, hostto, +ipto, portto, user, plugin, ttyrecfilee, params, timestampend, timestampendusec, returnvalue, comment, uniqid. +Refer to the open log and close log descriptions to get the meaning of each column. +Note that the enableAccountSqlLog option is required if you want the selfListSessions +and selfPlaySession plugins to work, as they use this database.

+
+
+

Note that enabling these on a very busy bastion (several new connections per second) can create lock contention, +especially on the global log: ensure you have a fast storage. In any case, if a connection can't get the lock after +a few seconds, it'll proceed anyway, and skip writing the sql log. In that case, if you enabled syslog or +local access logs, the globalsql and/or the accountsql field will contain the error detail.

+
+
+

Terminal recordings (ttyrec)

+

Every egress connection is started under ttyrec, which means that everything appearing on the console is recorded. +If a password is asked by some program, for example, and typing the password prints '*' or doesn't print +anything at all, this won't be recorded. This is by design. In other words, the keystrokes are not recorded, +except if they produce something on the screen.

+

The ttyrec files location is always /home/USER/ttyrec/REMOTEIP/file.ttyrec, where the actual file.ttyrec +name can be configured by the ttyrecFilenameFormat option. +By default, it'll contain the date, time, account, remote ip, port and user used to start the egress connection, +as well as the uniqid, for easier correlation between all the logs produced by the same connection. +Note that for long connections, or connections producing a lot of output, ttyrec files will be transparently rotated, +without interrupting the connection. +This is to avoid ending up with ttyrec files of several gigabytes that would still be opened, written to, +hence impossible to compress, encrypt, and push to an escrow filer. +The uniqid will be the same for all the ttyrec files corresponding to the same connection.

+

To play ttyrec files, you can either use selfPlaySession for yourself, or, +for admins having local access to the bastion machine, the ttyplay program can be used. +Another software, perhaps more powerful than ttyplay, can also be used: +IPBT (wiki), +aka "It's PlayBack Time", by the PuTTY author. +It can do more advanced things such as look for words appearing on any frame recorded in the ttyrec file, +play files using a logarithmic speed, or display an OSD with the exact time output you're seeing has appeared. +As ttyrec is a well-known format that has been around for a while, +there are a bunch of other programs you can use to read or convert these files.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/administration/mfa.html b/administration/mfa.html new file mode 100644 index 0000000..caa7ce5 --- /dev/null +++ b/administration/mfa.html @@ -0,0 +1,586 @@ + + + + + + + Multi-Factor Authentication — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Multi-Factor Authentication

+ +
+

Introduction

+
+

Flavors

+

The Bastion supports two flavors of Multi-Factor Authentication (MFA, sometimes called 2FA):

+
    +

  • Immediate MFA, mandatory on a per-account basis during the SSH authentication phase on the ingress side, +done by the system even before executing the bastion code, regardless of which actions (plugin calls, +remote connection, ...) are to be done by the account currently being authenticated

    • +

  • JIT MFA, done after the authentication phase, by the bastion code, conditionally (just-in-time), when +an action that is about to be done requires it by (configurable) policy

    • +
+

Each of these methods and their differences are detailed below, so you can choose the one that fits your environment.

+
+
+

Supported additional factors

+

The first factor is always the SSH publickey. Two additional factors are supported:

+ +
+
+
+

Immediate MFA

+

This method implements MFA directly using PAM during the initial SSH authentication phase, on the ingress +side, e.g. when accounts are connecting to the bastion. This entirely resides on SSH/PAM and doesn't even depend +on The Bastion code (appart from the setup side of the additional factor for each account).

+
+

Note

+

Use this method if you want to enable MFA for some or all accounts unconditionally, regardless of which action +they're about to conduct on The Bastion (i.e. use an --osh command, or attempt to connect somewhere, +or just display the help). If you want to enable MFA only for some precise --osh commands or some remote hosts, +you'll want to use JIT MFA instead.

+
+

This method requires proper configuration of both the SSH server, and PAM. The included templates of +/etc/ssh/sshd_config and /etc/pam.d/ssh files do support it out of the box.

+
+

Detailed explanation of the SSH server and PAM configuration

+

This works by modifying the AuthenticationMethods in sshd_config to add keyboard-interactive:pam, +which instructs the SSH server to rely on PAM for part of the authentication phase. Then, the PAM file defines +several authentications methods, which include several factors that can be configured per-account.

+
+

Note

+

You can skip this subsection if you're not interested in how this works exactly, but mainly want to know how +to setup MFA. If you're using the included sshd_config and pam.d/ssh templates unmodified, +which you are if you've followed the installation section, this will just work out of the box so you may skip +over the details and jump to How to use Immediate MFA.

+
+
+

sshd_config snippet

+

Let's take the last few lines of the ssh_config file and explain them step by step. These are where the +MFA logic is implemented. We've left the comments that can be found in the template, for clarity.

+
# If 2FA has been configured for root, we force pubkey+PAM for it. If this is the case
+# on your system, uncomment the next two lines (see
+# https://ovh.github.io/the-bastion/installation/advanced.html#fa-root-authentication)
+#Match User root
+#    AuthenticationMethods publickey,keyboard-interactive:pam
+
+
+

As explained in the comments within the file, this section (commented by default) refers to the MFA that can be +configured on the root account to protect The Bastion's own system. This is out of the scope of this documenation +section, as we're focusing on the users MFA here, so refer to the 2FA root authentication +section if that's what you want to achieve.

+
# Unconditionally skip PAM auth for members of the bastion-nopam group
+Match Group bastion-nopam
+    AuthenticationMethods publickey
+
+
+

The snipper above tells the SSH server to NOT rely on PAM (hence disable MFA) for accounts that are part of the +bastion-nopam group. This is an internal group that is used for accounts whose MFA setup has been set to +bypass PAM authentication, with the following command:

+
bssh --osh accountModify --account robot-sync --pam-auth-bypass yes
+╭──ac777d06bec9───────────────────────────────────────────the-bastion-3.12.00───
+│ ▶ modify the configuration of an account
+├───────────────────────────────────────────────────────────────────────────────
+│ Bypassing sshd PAM auth usage for this account...
+│ ... done, this account will no longer use PAM for authentication
+╰────────────────────────────────────────────────────────────</accountModify>───
+
+
+

This way, the account robot-sync will fall into the above configuration section Match case and end up +only using classic publickey authentication, hence no MFA. As MFA is only meaningful for humans, use this setting +for accounts that are used by any automated process you might have that interact with the bastion (for example using +its JSON API).

+
# if in one of the mfa groups AND the osh-pubkey-auth-optional group, use publickey+pam OR pam
+Match Group mfa-totp-configd,mfa-password-configd Group osh-pubkey-auth-optional
+    AuthenticationMethods publickey,keyboard-interactive:pam keyboard-interactive:pam
+
+
+

The snippet above tells SSH that for accounts having an authentication factor configured, namely either a TOTP or +a password, and having the "public key is optional" flag, set by --osh accountModify --pubkey-auth-optional, +implies that those accounts can either authenticate through public key and an additional factor (through PAM), +or through PAM only. In essence these accounts may use only a password, or a TOTP, or both, without having a +public key in addition to the other factors. Hence, this is not MFA per-se, but is an additional functionaly available +should you need this in your environment. You may remove (or comment) the two lines above if you're confident you'll +never require the pubkey-auth-optional feature.

+
# if in one of the mfa groups, use publickey AND pam
+Match Group mfa-totp-configd,mfa-password-configd
+    AuthenticationMethods publickey,keyboard-interactive:pam
+
+
+

The snippet above is the core of the mandatory MFA configuration of the SSH server: it instructs the SSH server to +authenticate accounts that have at least one MFA factor configured with their public key first, then hand over the +authentication phase to PAM to check the additional factors.

+
# by default, always ask the publickey (no PAM)
+Match All
+    AuthenticationMethods publickey
+
+
+

Finally, the snippet above is for the general case, i.e. accounts not having MFA configured, in which case they're +authenticated using their public key only.

+
+
+

PAM ssh snippet

+

The template is heavily commented<https://github.com/ovh/the-bastion/blob/master/etc/pam.d/sshd.debian12>, line by line, please have a look at it if you want to know more.

+
+
+
+

How to use Immediate MFA

+

If you want to setup immediate MFA, you'll need to setup the SSH server and PAM configurations correctly, as explained +above. If you installed the provided templates for both (which is the default), you're good to go.

+

You may want either to enable MFA for all the accounts existing on your bastion, or only a subset of these users, +read on the proper section below for each case.

+
+

Requiring all users to setup their MFA

+

To ensure no user can use their account without configuring their MFA first, you have to set the accountMFAPolicy +option of bastion.conf to either any-required, totp-required or password-required. Detailed +information about this configuration setting is available +here.

+

When this setting is configured to any of the 3 above values, no interaction will be allowed on the bastion (such as +using plugins or connecting to a remote asset) as long as the user didn't set up their MFA:

+
bssh --osh selfListAccesses
+│
+│ ⛔ Sorry johndoe, but you need to setup the Multi-Factor Authentication before using this bastion, please use either the `--osh selfMFASetupPassword' or the `--osh selfMFASetupTOTP' option, at your discretion, to do so
+
+
+

The only allowed --osh commands allowed in such a case are help, info and the two ones referenced in the +above error message, precisely to be able to setup the MFA on the account.

+

In this mode, if you want to exclude a few accounts from requiring MFA (if you have accounts that are used by +automation or any other M2M workflow), you can do so using accountModify --pam-auth-bypass yes.

+
+
+

Requiring only a subset of users to setup their MFA

+

If instead of forcing all users to require MFA, you want to require a precise subset of users to have MFA, you should +leave the accountMFAPolicy to enabled, and set the requirement flag on a per-account basis. This can be +done using accountModify --mfa-password-required yes and/or accountModify --mfa-totp-required yes. If you +set both flags on the same account, the bastion will require both factors to be set and provided on authentication, +in addition to publickey authentication. In this case, 3 authentication factors would be required. This is why we +call it MFA instead of 2FA: the number of additional factors you want is configurable.

+
+
+
+
+

JIT MFA

+

This method implements MFA checking right before an action is allowed, depending on the bastion policy, instead of +requiring it at the ingress authentication stage.

+
+

Note

+

Use this method if you want to enable MFA on a per-action basis. In this case, The Bastion will decide whether +providing additional authentication factors is required right before a specific action is requested (such as +connection to a given remote asset, or execution of a subset of --osh commands). +You may also want to use this method if for some reason you can't setup the sshd_config file +as required by the Immediate MFA method

+
+

Note that the different ways detailed below can be cumulated: you might want to enable MFA for a few plugins, along +with enabling it for sensitive remote hosts present in specific bastion groups, in addition to a few sensitive +accounts that would require it no matter what.

+
+

Proper setup of sshd_config

+

To use JIT MFA, your first have to disable Immediate MFA, as is the default if you're using the provided +configuration template for your SSH server (which you are if you followed the default installation steps). +You'll need to comment out two lines within the /etc/ssh/sshd_config file, these are located near the +end of the file:

+
# if in one of the mfa groups, use publickey AND pam
+#Match Group mfa-totp-configd,mfa-password-configd
+#    AuthenticationMethods publickey,keyboard-interactive:pam
+
+
+

You'll need to reload the SSH daemon for this to be taken into account. The next subsections explain how to setup +policies depending on the actions you want to protect through JIT MFA.

+
+
+

On a per-plugin basis

+

First ensure you've followed the Proper setup of sshd_config.

+

To force MFA for a plugin, you may add the mfa_required option to its configuration. This configuration parameter +allows 4 values:

+
    +

  • any, in which case MFA is required with any supported factor (currently either password or TOTP)

    • +

  • password, in which case a password is required in addition to publickey authentication

    • +

  • totp, in which case a TOTP is required in addition to publickey authentication

    • +

  • none, in which case no MFA is required (which is the default if the mfa_required setting is omitted)

    • +
+

To enable MFA for the adminSudo plugin, for example, you may add:

+
{
+   "mfa_required": "any"
+}
+
+
+

to the /etc/bastion/plugin.adminSudo.conf file. Please ensure that this file is readable by the +bastion-users system group (as all /etc/bastion/plugin.*.conf files should be), so that the code running +under the bastion users permissions can read it.

+

When configured like this, usage of the adminSudo plugin, in our example, will trigger the validation of additional +authentication factors. +Note that for this to work, you must have the /etc/pam.d/ssh file set up correctly, +as we're using PAM for this. The provided template is advised, and you're already using it if you followed the +default installation steps. +If you are not sure you're using the provided template, you may compare your current /etc/pam.d/ssh file +with the proper template for your distro, which can be found in /opt/bastion/etc/pam.d/sshd.*.

+

As you see, the MFA phase will be fired up for this plugin, but not for the info plugin for example:

+
bssh --osh adminSudo
+As this is required to run this plugin, entering MFA phase for johndoe.
+Your account has Multi-Factor Authentication enabled, an additional authentication factor is required (password).
+Your password expires on 2023/10/31, in 89 days
+Password: ^C
+
+bssh --osh info
+╭──ac777d06bec9───────────────────────────────────────────the-bastion-3.12.00───
+│ ▶ information
+├───────────────────────────────────────────────────────────────────────────────
+│ You are johndoe
+[...]
+
+
+
+
+

On a per-group basis

+

First ensure you've followed the Proper setup of sshd_config.

+

If you want to ensure that MFA is required to connect to a remote host through a bastion group, +you should tag this group to require MFA. To do this, use the groupModify command:

+
guybrush@bastion1(master)> groupModify --group securegroup --mfa-required any
+╭──ac777d06bec9───────────────────────────────────────────the-bastion-3.12.00───
+│ ▶ modify the configuration of a group
+├───────────────────────────────────────────────────────────────────────────────
+│ Modifying mfa-required policy of group...
+│ ... done, policy is now: any
+╰──────────────────────────────────────────────────────────────</groupModify>───
+
+guybrush@bastion1(master)> groupInfo --group securegroup
+╭──ac777d06bec9───────────────────────────────────────────the-bastion-3.12.00───
+│ ▶ group info
+├───────────────────────────────────────────────────────────────────────────────
+│ Group securegroup's Owners are: guybrush
+[...]
+│ ❗ MFA Required: when connecting to servers of this group, users will be asked for an additional authentication factor
+[...]
+
+guybrush@bastion1(master)> ssh root@127.1.2.3
+│ Welcome to bastion1, guybrush, your last login was 00:00:27 ago (Wed 2023-08-02 15:36:03 UTC) from 172.17.0.1(172.17.0.1)
+[...]
+
+ will try the following accesses you have:
+  - group-member of securegroup with ED25519-256 key SHA256:94yETEnnWUy9yTG1dgAdXgunq6zzJPjlddFXjUH0Czw [2023/03/03]  (MFA REQUIRED: ANY)
+
+As this is required for this host, entering MFA phase for guybrush.
+Your account has Multi-Factor Authentication enabled, an additional authentication factor is required (password).
+Your password expires on 2023/10/31, in 89 days
+Password:
+
+
+

As you see, after setting the flag on the group, attempting to access an asset that is part of the group (see +groupListServers) will require MFA.

+
+

Note

+

If an account has access to an asset via several groups, MFA will be required if at least one group requires it. +Hence, a good way to ensure that all connections to an asset will require MFA would be to list the +SSH keys on the remote server, match those to groups on the bastion, and ensure they all have --mfa-required enabled.

+
+
+
+

On a per-account basis

+

You may also use this method to enable MFA on a per-account basis (as is possible with the Immediate MFA method).

+

To do this, you should follow the same steps than are outlined in the Requiring only a subset of users to setup their MFA subsection of the Immediate MFA setup.

+

The only difference will be in your sshd_config file, as for JIT MFA your should ensure you've followed the Proper setup of sshd_config.

+

In the case of Immediate MFA, the uncommented sshd_config file block asks the SSH server to hand over authentication to PAM, hereby +requiring MFA at the authentication phase. For the JIT MFA on a per-account basis, this configuration is disabled, but the bastion code, after the +authentication phase is over, verifies whether the account requires to provide additional authentication factors, and triggers a PAM call if this +is the case.

+
+
+

Bypassing MFA for automated workflows

+

If you have accounts that are used for automation, you'll want to exclude them from requiring MFA.

+

To do this, use --osh accountModify --mfa-password-required bypass --mfa-totp-required bypass. Accounts +with this setting will no longer require to enter additional credentials even when the policy of JIT MFA would +require them to.

+
+
+
+

Additional information

+
+

MFA and interactive mode

+

When using the interactive mode, and JIT MFA, attempting to conduct an action that requires MFA will trigger the MFA authentication phase, as expected.

+

However, when multiple MFA-required operations are to be done back to back, as is often the case when interactive mode +is used, the MFA authentication phase will be triggered for each and every action, which can be cumbersome.

+

As long as interactiveModeProactiveMFAenabled is true, users can use the mfa command in interactive +mode, to trigger the MFA authentication phase proactively, and enter an elevated session that will not require to enter MFA again. This elevated session +will expire after interactiveModeProactiveMFAexpiration seconds (15 minutes by default). Users can exit +the elevated session manually by typing nomfa.

+

Here is how it looks like:

+
bssh -i
+
+Welcome to bastion1 interactive mode, type `help' for available commands.
+You can use <tab> and <tab><tab> for autocompletion.
+You'll be disconnected after 60 seconds of inactivity.
+Loading... 90 commands and 0 autocompletion rules loaded.
+
+guybrush@bastion1(master)> mfa
+As proactive MFA validation has been requested, entering MFA phase.
+Your account has Multi-Factor Authentication enabled, an additional authentication factor is required (password).
+Your password expires on 2023/10/31, in 88 days
+Password:
+pamtester: successfully authenticated
+Proactive MFA enabled, any command requiring MFA from now on will not ask you again.
+This mode will expire in 00:15:00 (Thu 2023-08-03 12:35:08 UTC)
+To exit this mode manually, type 'nomfa'.
+
+guybrush@bastion1(master)[MFA-OK]> groupAddServer
+╭──ac777d06bec9───────────────────────────────────────────the-bastion-3.12.00───
+│ ▶ adding a server to a group
+├───────────────────────────────────────────────────────────────────────────────
+[...]
+
+guybrush@bastion1(master)[MFA-OK]> nomfa
+Your proactive MFA validation has been forgotten.
+
+guybrush@bastion1(master)>
+
+
+

As you seen, once mfa has been entered and the MFA validated, the prompt changes to [MFA-OK] implying that +any command usually requiring MFA will not ask for it again (such as groupAddServer in the above example, as +we've configured it to). We then explicitely exit the MFA elevated session by entering nomfa.

+
+
+

MFA and --osh batch

+

The batch plugin is useful to enter several --osh commands in a batch way. However, if +any of those commands require MFA, it would ask us repeatedly for our MFA, which can be cumbersome.

+

To avoid this behavior, and if you know that some of the commands you want to use in batch more will require MFA, +you may use the --proactive-mfa option to the bastion, which will ask for your MFA before executing the +batch plugin, and any command requiring MFA will not ask for it again:

+
bssh --proactive-mfa --osh batch
+
+As proactive MFA has been requested, entering MFA phase for guybrush.
+Your account has Multi-Factor Authentication enabled, an additional authentication factor is required (password).
+Your password expires on 2023/11/01, in 89 days
+Password:
+pamtester: successfully authenticated
+╭──ac777d06bec9───────────────────────────────────────────the-bastion-3.12.00───
+│ ▶ batch
+├───────────────────────────────────────────────────────────────────────────────
+│ Feed me osh commands line by line on stdin, I'll execute them sequentially.
+│ Use 'exit', 'quit' or ^D to stop.
+│ --- waiting for input
+[...]
+
+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/administration/security_advisories.html b/administration/security_advisories.html new file mode 100644 index 0000000..98b1b94 --- /dev/null +++ b/administration/security_advisories.html @@ -0,0 +1,157 @@ + + + + + + + Security Advisories — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Security Advisories

+

This section contains all the security advisories since The Bastion has been published.

+

If you find any behavior or bug that you suspect might have a security impact, please +report it here.

+
+

CVE List

+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/administration/security_advisories/cve_2023_45140.html b/administration/security_advisories/cve_2023_45140.html new file mode 100644 index 0000000..abf2f45 --- /dev/null +++ b/administration/security_advisories/cve_2023_45140.html @@ -0,0 +1,236 @@ + + + + + + + CVE-2023-45140 — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

CVE-2023-45140

+
    +

  • Severity: 4.8 (CVSS V3)

    • +

  • Vector: CVSS:3.1/AV:N/AC:L/PR:H/UI:R/S:C/C:L/I:L/A:N

    • +

  • Affected versions: from 3.0.0 included to 3.14.15 excluded

    • +

  • Patched versions: 3.14.15 and up

    • +
+

This advisory is also available online.

+
+

Summary

+

SCP and SFTP plugins don't honor group-based and account-based JIT MFA.

+
+
+

Details

+

Establishing a SCP/SFTP connection through The Bastion via a group access where MFA is enforced does not ask for additional factor. This abnormal behavior only applies to per-group-based JIT MFA and JIT MFA on a per-account basis.

+

Other MFA setup types, such as Immediate MFA and JIT MFA on a per-plugin basis are not affected.

+

Normal SSH access (i.e. not SCP nor SFTP) is not affected.

+
+
+

How to reproduce for group-based JIT MFA

+
    +

  • Create a group

    • +

  • Apply groupModify --mfa-required any to this group

    • +

  • Grant SSH access to someone via this group on a given IP

    • +

  • Grant scp download right (or sftp right) to the same person via this group on the same IP

    • +

  • This group should now force MFA for any connection of the person allowed through the group's rights set. This is the case for SSH, but not for SCP or SFTP as would be expected.

    • +
+
+
+

How to reproduce for account-based JIT MFA

+
    +

  • Create an account

    • +

  • Apply accountModify --personal-egress-mfa-required any to this account

    • +

  • Grant a personal SSH access to this account on a given IP

    • +

  • Grant scp download right (or sftp right) to the same account via their personal access on the same IP

    • +

  • This account should now have forced MFA for any egress connection allowed through their personal rights set. This is the case for SSH, but not for SCP or SFTP as would be expected.

    • +
+
+
+

Impact for group-based JIT MFA

+

For an actor to be able to bypass MFA for scp/sftp to a given remote server, ALL the following conditions must apply:

+
    +

  • The target server must be part of a group (and have the egress group's public key trusted in its authorized_keys file)

    • +

  • The group must have JIT MFA enabled on it (through groupModify --mfa-required any)

    • +

  • The actor must have an account on the bastion

    • +

  • The actor must be a member of the group (granted by the groups's gatekeepers)

    • +

  • scp and/or sftp must be globally enabled on the bastion (this is the default)

    • +

  • scp and/or sftp must be explicitly allowed to the given remote server through the group (granted by the groups's aclkeepers)

    • +
+

When all conditions above apply, the actor would be able to use scp or sftp on the target server without requiring to provide an additional factor where it should.

+
+
+

Impact for account-based JIT MFA

+

For an actor to be able to bypass MFA for scp/sftp to a given remote server, ALL the following conditions must apply:

+
    +

  • The target server must be part of the actor's account personal accesses (and have the account's egress public key trusted in its authorized_keys file)

    • +

  • The account must have JIT MFA enabled on it (through accountModify --personal-egress-mfa-required any)

    • +

  • scp and/or sftp must be globally enabled on the bastion (this is the default)

    • +

  • scp and/or sftp must be explicitly allowed to the given remote server through this account's personal accesses (granted by either selfAddPersonalAccess or accountAddPersonalAccess)

    • +
+

When all conditions above apply, the actor would be able to use scp or sftp on the target server without requiring to provide an additional factor where it should.

+
+
+

Mitigation

+

If you don't use the per-group-based JIT MFA on any of your groups (through groupModify --mfa-required), and don't use the JIT MFA on a per-account basis (through accountModify --personal-egress-mfa-required), you don't need to mitigate the issue as you don't use the impacted feature (see above for impact details).

+

Otherwise, if you can't immediately upgrade to v3.14.15 or more recent, and you feel that the aforementioned impacts are important enough in your environment, you may choose to temporarily disable the scp and sftp plugins globally on the bastion, by setting "disabled": true in these plugins configuration files, which can be found in /etc/bastion/plugin.scp.conf and /etc/bastion/plugin.sftp.conf respectively. If these files don't exist, create them with the contents as { "disabled": true }. They should be readable by anyone but modifiable only by root (i.e. chmod 664; chown root:root)

+
+
+

Timeline

+
    +

  • 2023-10-06: security bug report filed on GitHub

    • +

  • 2023-10-06: bug report accepted and confirmed as having a security impact

    • +

  • 2023-10-11: CVE ID requested

    • +

  • 2023-10-11: CVE ID assigned

    • +

  • 2023-11-07: fix pushed to a private fork for review

    • +

  • 2023-11-08: v3.14.15 released with the fix

    • +
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/development/setup.html b/development/setup.html new file mode 100644 index 0000000..1dcab3a --- /dev/null +++ b/development/setup.html @@ -0,0 +1,318 @@ + + + + + + + Environment setup — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Environment setup

+ +

This documentation section outlines the few steps needed to build a development environment for The Bastion, +easing code modification, tests, checks, and ultimately, pull requests.

+
+

Available tools

+

The provided docker/devenv/run-tool.sh script will build a development docker for you, under which it'll +run several tools. Your local git folder will be mounted as a volume inside this docker so that it can +access the files, and potentially modify them (such as for perltidy).

+

The supported tools are as follows:

+
Usage: ./docker/devenv/run-tool.sh COMMAND [OPTIONS]
+
+  COMMAND may be one of the following:
+
+  tidy       [FILES..] runs perltidy on several or all the Perl source files, modifying them if needed
+  tidycheck  [FILES..] runs perltidy in dry-run mode, and returns an error if files are not tidy
+  perlcritic           runs perlcritic on all the Perl source files
+  shellcheck [FILES..] runs shellcheck on all the shell source files
+  lint                 runs tidy, perlcritic and shellcheck on all files in one command
+  doc                  generates the documentation
+  sphinx-view-objects  shows the named objects of the Sphinx documentation that can be referenced
+  rebuild              forces the rebuild of the devenv docker image that is needed to run all the above commands
+  run <COMMAND>        spawn an interactive shell to run any arbitrary command in the devenv docker
+  doc-serve <PORT>     starts a local HTTP python server on PORT to view generated documentation
+
+
+

Before submitting a pull request, you'll need at minimum to run lint. It might be a good idea to setup a +git pre-commit hook to do this on modified files, see below.

+
+
+

Git pre-commit hook

+

Some lint checks are enforced through GitHub Actions, but it'll save you a lot of back-and-forth if you ensure that +these checks are passing locally on your development environment.

+

To this effect, you'll need to setup pre-commit hooks on your local copy of the git repository, so that your code +is automatically checked by perlcritic, perltidy and shellcheck each time you commit.

+

If you previously cloned the repository with such a command:

+
git clone https://github.com/ovh/the-bastion
+
+
+

Then you can copy the provided pre-commit script into your local .git folder:

+
cp contrib/git/pre-commit .git/hooks/pre-commit
+
+
+

To verify that it works checkout a new test branch and add two dummy files like this:

+
git checkout -B mybranch
+printf "%b" "#! /usr/bin/env bash\nunused=1\n" > bin/shell/dummy.sh
+printf "%b" "#! /usr/bin/env perl\nsub dummy { 1; };\n" > lib/perl/dummy.pm
+git add bin/shell/dummy.sh lib/perl/dummy.pm
+git commit -m dummy
+
+*** Checking shell files syntax using system shellcheck
+`-> bin/shell/dummy.sh
+
+In bin/shell/dummy.sh line 2:
+unused=1
+^----^ SC2034: unused appears unused. Verify use (or export if used externally).
+
+`-> [ERR.]
+
+ERROR: shell-check failed on bin/shell/dummy.sh
+*** Checking perl tidiness
+`-> lib/perl/dummy.pm
+./lib/perl/dummy.pm ./lib/perl/dummy.pm.tdy differ: char 38, line 2
+--- ./lib/perl/dummy.pm 2023-10-03 08:19:55.605950307 +0000
++++ ./lib/perl/dummy.pm.tdy     2023-10-03 08:20:43.618577295 +0000
+@@ -1,2 +1,2 @@
+ #! /usr/bin/env perl
+-sub dummy { 1; };
++sub dummy { 1; }
+
+ERROR: perl tidy failed on lib/perl/dummy.pm
+
+!!! COMMIT ABORTED !!!
+If you want to commit nevertheless, use -n.
+
+
+

As you see, the checks are running before the commit is validated and abort it should any check fail.

+
+
+

Running integration tests

+
+

Using Docker

+

Functional tests use Docker to spawn an environment matching a bastion install. +One of the docker instances will be used as client, which will connect to the other instance +which is used as the bastion server. The client instance sends commands to the server instance +and tests the return values against expected output.

+

To test the current code, use the following script, which will run docker build and launch the tests:

+
tests/functional/docker/docker_build_and_run_tests.sh <TARGET>
+
+
+

Where target is one of the supported OSes. Currently only Linux targets are supported. +You'll get a list of the supported targets by calling the command without argument.

+

For example, if you want to test it under Debian (which is a good default OS if you don't have any preference):

+
tests/functional/docker/docker_build_and_run_tests.sh debian12
+
+
+

The full tests usually take 25 to 50 minutes to run, depending on your hardware specs. +If you want to launch only a subset of the integration tests, you may specify it:

+
tests/functional/docker/docker_build_and_run_tests.sh debian12 --module=320-base.sh
+
+
+

Other options are supported, and passed through as-is to the underlying test script, use --help as below to +get the list (the output in this documentation might not be up to date, please actually launch it yourself +to get up-to-date information):

+
tests/functional/launch_tests_on_instance.sh --help
+
+Usage: /home/user/bastion/tests/functional/launch_tests_on_instance.sh [OPTIONS] <IP> <SSH_Port> <HTTP_Proxy_Port_or_Zero> <Remote_Admin_User_Name> <Admin_User_SSH_Key_Path> <Root_SSH_Key_Path>
+
+Test Options:
+    --skip-consistency-check   Speed up tests by skipping the consistency check between every test
+    --no-pause-on-fail         Don't pause when a test fails
+    --log-prefix=X             Prefix all logs by this name
+    --module=X                 Only test this module (specify a filename found in `functional/tests.d/`), can be specified multiple times
+
+Remote OS directory locations:
+    --remote-etc-bastion=X     Override the default remote bastion configuration directory (default: /etc/bastion)
+    --remote-basedir=X         Override the default remote basedir location (default: /home/user/bastion)
+
+Specifying features support of the underlying OS of the tested bastion:
+    --has-ed25519=[0|1]        Ed25519 keys are supported (default: 1)
+    --has-mfa=[0|1]            PAM is usable to check passwords and TOTP (default: 1)
+    --has-mfa-password=[0|1]   PAM is usable to check passwords (default: 0)
+    --has-pamtester=[0|1]      The `pamtester` binary is available, and PAM is usable (default: 1)
+    --has-piv=[0|1]            The `yubico-piv-tool` binary is available (default: 1)
+    --has-sk=[0|1]             The openssh-server supports Secure Keys (FIDO2) (default: 0)
+
+
+
+
+

Without Docker

+
+

Note

+

This method is discouraged, prefer using the Docker method above when possible

+
+

You can test the code against a BSD (or any other OS) without using Docker, by spawning a server +under the target OS (for example, on a VM), and installing the bastion on it.

+

Then, from another machine, run:

+
test/functional/launch_tests_on_instance.sh <IP> <port> <remote_user_name> <ssh_key_path> [outdir]
+
+
+

Where IP and port are the information needed to connect to the remote server to test, +remote_user_name is the name of the account created on the remote bastion to use for the tests, +and ssh_key_path is the private SSH key path used to connect to the account. +The outdir parameter is optional, if you want to keep the raw output of each test.

+

This script is also the script used by the Docker client instance, +so you're sure to get the proper results even without using Docker.

+

Please do NOT run any of those tests on a production bastion!

+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/development/tests.html b/development/tests.html new file mode 100644 index 0000000..aea2715 --- /dev/null +++ b/development/tests.html @@ -0,0 +1,361 @@ + + + + + + + Writing tests — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Writing tests

+ +

When modifying code, adding features or fixing bugs, you're expected to write one or more tests to ensure that +the feature your adding works correctly, or that the bug you've fixed doesn't come back.

+

Integration tests modules live in the tests/functional/tests.d folder. +You may either add a new file to test your feature, or modify an existing file.

+

These modules are shell scripts, and are sourced by the main integration test engine. Having a look at one of +these modules will help you understand how they work, the tests/functional/tests.d/320-base.sh is a good +example you might want to look at.

+
+

Example

+

Here is a simple test taken from 320-base.sh:

+
+
a simple test
+
success   help2     $a0 --osh help
+contain "OSH help"
+json .error_code OK .command help .value null
+
+
+
+

A complete reference of such commands can be found below, but let's explain this example in a few words:

+

The command success implies that we're running a new test command, and that we expect it to work (we might +also want to test invalid commands and ensure they fail as they should). +The tester docker will connect to the target docker (that is running the bastion code) as a bastion user, and +run the --osh help command there. This is expected to exit with a code indicating success (0), +otherwise this test fails.

+

The output of the command, once run on the bastion, should contain the text OSH help, or the test will fail.

+

In the JSON output (see JSON API) of this command, we expect to find the error_code field set to OK, +the command field set to help, and the value field set to null, or the test will fail.

+

Running just this test will yield the following output:

+
+
a simple test output
+
00m04 [--] *** [0010/0021] 320-base::help2 (timeout --foreground 30 ssh -F /tmp/bastiontest.pgoA5h/ssh_config -i /tmp/bastiontest.pgoA5h/account0key1file user.5000@bastion_debian10_target -p 22 -- --json-greppable --osh help)
+00m05 [--] [ OK ] RETURN VALUE (0)
+00m05 [--] [ OK ] MUST CONTAIN (OSH help)
+00m05 [--] [ OK ] JSON VALUE (.error_code => OK) [  ]
+00m05 [--] [ OK ] JSON VALUE (.command => help) [  ]
+00m05 [--] [ OK ] JSON VALUE (.value => null) [  ]
+
+
+
+

As you can see, this simple test actually checked 5 things: the return value, whether the output text contained +a given string, and 3 fields of the JSON output.

+
+
+

Reference

+

These are functions that are defined by the integration test engine and should be used in the test modules.

+
+

Launch a test

+
+

run

+
+

syntax

+
    +

  • run <name> <command>

    • +
+
+

This function runs a new test named <name>, which will execute <command> on the tester docker. +Usually <command> will connect to the target docker (running the bastion code) using one of the test accounts, +and run a command there.

+

A few accounts are preconfigured:

+
    +

  • The main account ("account 0"): this one is guaranteed to always exist at all times, and is a bastion admin. +There are a few variables that can be referenced to use this account:

    +
      +

    • $a0 is the ssh command-line to connect to the remote bastion as this account

      • +

    • $account0 is the account name, to be used in parameters of --osh commands where needed

      • +
    +
    • +

  • A few secondary accounts that are created, deleted, modified during the tests:

    +
      +

    • $a1, $a2 and $a3 are the ssh command-lines to connect to the remote bastion as these accounts

      • +

    • $account1, $account2 and $account3 are the accounts names

      • +
    +
    • +

  • Another special non-bastion-account command exists:

    +
      +

    • $r0 is the required command-line to directly connect to the remote docker on which the bastion code is running, +as root, with a bash shell. Only use this to modify the remote bastion files, such as config files, between tests

      • +
    +
    • +
+

A few examples follow:

+
+
running a few test commands
+
run test1 $a0 --osh info
+run test2 $a0 --osh accountInfo --account $account1
+run test3 $a1 --osh accountDelete --account $account2
+
+
+
+

Note that the run function just runs the given command, but doesn't check whether it exited normally, you'll +need other functions to verify this, see below.

+
+
+

success

+
+

syntax

+
    +

  • success <name> <command>

    • +
+
+

This function is exactly the same as the run command above, except that it expects the given <command> to +return a valid error code (zero). Most of the time, you should be using this instead of run, except if you're +expecting the command to fail, in which case you should use run + retvalshouldbe, see below.

+
+
+

plgfail

+
+

syntax

+
    +

  • plgfail <name> <command>

    • +
+
+

This function is exactly the same as the run command above, except that it expects the given <command> to +return an error code of 100, which is the standard exit value when an osh command fails.

+

This function is equivalent to using run followed by retvalshouldbe 100 (see below).

+
+
+
+

Verify a test validity

+
+

retvalshouldbe

+
+

syntax

+
    +

  • retvalshouldbe <value>

    • +
+
+

Verify that the return value of a test launched right before with the run function is <value>. +You should use this if you expect the previous test to return a non-zero value.

+

Note that the success function is equivalent to using run followed by retvalshouldbe 0.

+
+
+

contain

+
+

syntax

+
    +

  • contain <text>

    • +

  • contain REGEX <regex>

    • +
+
+

This function verifies that the output of the test contains a given <text>. If you need to use a regex +to match the output, you can use the contain REGEX construction, followed by the regex.

+
+
+

nocontain

+
+

syntax

+
    +

  • nocontain <text>

    • +

  • nocontain REGEX <regex>

    • +
+
+

This function does the exact opposite of the contain function just above, and ensure that a given text +or regex is NOT present in the output.

+
+
+

json

+
+

syntax

+
    +

  • json <field1> <value1> [<field2> <value2> ...]

    • +
+
+

This function checks the JSON API output of the test, and validates that it contains the correct value for each +specified field. The <fieldX> entries must be valid jq filters.

+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/faq.html b/faq.html new file mode 100644 index 0000000..dac164a --- /dev/null +++ b/faq.html @@ -0,0 +1,300 @@ + + + + + + + FAQ — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

FAQ

+
+

"The Bastion", really?

+

We've been using this software for quite a while at OVHcloud, and there it has always been known as "the bastion": +nobody ever bothered to find a fancy name for it. +So, when we decided to release it in opensource, the naming problem arose. +After going through some possible names, we realized that nothing would work, as everybody would keep +naming it "the bastion" anyway, so, we decided to call it just The Bastion.

+
+
+

Why using common::sense?

+

Because it's usually a good idea to ensure you use common::sense before writing code! +On a more serious note, this is almost like using strict and warnings, +but with a very reduced memory footprint. +When you run a bastion with thousands of simultaneous active sessions with that many users, it starts to matter.

+
+
+

Why Perl?

+

There is probably and endless list of why it's the perfect language for this, +and another similarly endless list of why Perl is completely irrelevant and other $COOL_LANGUAGE would be a better fit, +but some "why" reasons include:

+
    +

  • It works everywhere, and most OSes have it installed by default

    • +

  • Perl has this cool "taint" mode that adds security to untrusted program inputs, we use this on sensitive code

    • +

  • One of the design choice of The Bastion has always been to be very close to the system, +leveraging some low-level Operating System functions, which are easier to interact with using a scripting language

    • +

  • The Bastion has a loose origin from an old script written at OVHcloud in the early days, +back when the de-facto usual language used internally was Perl

    • +
+
+
+

Why not using a PKI?

+

Well, you can, of course! However this is a very centralized way of managing your accesses, +with all the power in the hands of whoever controls your CA. +It can be a highly successful if done very carefully, with a lot of security and processes around the +certificates delivery workflows. Managing a CA correctly is no joke and can bite you quite hard if done improperly. +This also happens to be a somewhat recent addition to OpenSSH, and if you have a lot of heterogeneous +systems to handle, this might be a no-go. +You can read more about this topic here: https://blog.ovhcloud.com/the-ovhcloud-bastion-part-1/

+
+
+

What does osh mean in --osh?

+

This has long been forgotten. Some people say it used to mean "Ovh SHell" at some point, +but nobody knows whether it's true or just a legend.

+
+ +
+

Can I run it under Docker in production?

+

Technically you can, but you have to think about what are the implications (this is true regardless +of the containerization technology). What's important to understand is that it adds another layer of abstraction, +and can give you a false sense of security. +If you either have the complete control of the host running Docker (and hardened it properly), +or you fully trust whoever is running the host for you, then this is fine. +Otherwise, somebody might have access to all your keys and you have no way to know or block it.

+

Note that the provided Dockerfiles are a good start, but no volumes are defined. +To ensure that all the accounts don't disappear on a docker rm, you would at least need to ensure that +/home, /etc/passwd, /etc/shadow, /etc/group, /etc/gshadow are stored in a volume, +in addition to /etc/bastion and /root/.gpg. +You'll also need an SSH server, obviously, and probably a syslog-ng daemon.

+
+
+

Can I install it on my already existing server?

+

This is discouraged if your server is already doing something else, such as hosting a website, +handling your e-mails or running a database.

+

From a security standpoint, it's a bad idea because if your server gets hacked due to one of +the other services you're hosting, the SSH keys could get compromised even if The Bastion itself has no security issue.

+

This is also discouraged due to the design of The Bastion: being deeply intertwined with the OS it's running on, +it might make changes that seem intrusive from the point of view of other running services. +Such as creating and deleting system accounts and groups from time to time, modifying the PAM configuration, +or hardening the SSH client and server configurations system-wide, +which could break other services or workflows that expect to be running on a default (non-hardened) SSH configuration.

+
+
+

How to use The Bastion with the SSH ProxyCommand option?

+

tl;dr: you can't.

+

Fast answer: you can't, because The Bastion is not a proxy, nor what is often called an "ssh jumphost". +Granted, sometimes these are also called "bastions", hence the confusion. +Note that this also applies to the -J or JumpHost ssh option, which is just a simplified ProxyCommand.

+

Long answer: The Bastion is acting as a trusted party between you (the admin or the robot) and the server +of the infrastructure you need to access. To achieve this, when you use the bastion to connect to the server, +there are two distinct ssh connections present at the same time:

+
+
    +

  • The ingress ssh connection, between you and the bastion. +For this connection your local private ssh key is used to authenticate yourself to the bastion

    • +

  • The egress ssh connection, between the bastion and the remote server you need to access. +For this connection your bastion egress private ssh key (or a group egress private ssh key you're member of) +is used to authenticate the bastion to the remote server

    • +
+
+

Those two connections are distinct, and the bastion logic merges those two so that you're under the impression +that you're directly connected to the remote server. There is no dynamic port forwarding happening on the bastion +to enable access to the remote server from your desktop, network-wise (which is what JumpHost does).

+

Using ProxyCommand with the bastion doesn't make sense because with this option, your local ssh client expects +to talk the SSH dialect on the STDIN of the ProxyCommand you're giving, and it'll try to use your local SSH key +to authenticate you through it, which won't work as it's only used for the ingress connection. +However, when you use the usual bastion alias, in STDIN you have the remote server terminal directly, +all the SSH stuff has already been done.

+

Attempting to summarize this a bit would be: ProxyCommand and JumpHost are useful when the server +you're trying to connect to can't be accessed network-wise from where you stand, and needs to be accessed +through some kind of proxy instead, where The Bastion's logic is to use two distinct SSH connections, +and two distinct authentication phases, with two distinct SSH keys (yours for the ingress connection, +and your bastion egress key for the egress connection).

+
+
+

What is session locking?

+

Session locking can be enabled in the global configuration, through the idleLockTimeout option.

+

When enabled, the interactive SSH session will automatically lock itself after a defined amount of idle time. +Unlocking such a session can be done, but re-authentication is required, i.e. connecting to the bastion +from another console, and using the unlock command. +Here, idle time is defined as keyboard input idle time, so even if a remote command might be running +(such as tail -f), the connection will still be considered idle if no input is detected. This is by design.

+

Such as configuration can be required by policy or regulations, in some sensitive environments, +to ensure opened connections are automatically cut off when unused. +Locking such sessions can be an alternative to cutting (see the idleKillTimeout option) as it gives +a chance to unlock the session before tearing the connection down. +Both can also be used, such as locking first, then tearing down after more time has passed without the session +being unlocked. Note that while a session is locked, any potentially running remote command will still be running, +as locking the session will just hide the normal console output, and prevent any input to be registered. +Unlocking the session will simply resume display to the console. +Session locking can be seen as the equivalent of a desktop screensaver, but for SSH interactive sessions.

+

A locked session looks like this:

+_images/locked_session.png +
+
+

Can I use Ansible over The Bastion?

+

Yes, you can, by using a wrapper available here.

+

Please note however that some Ansible modules may not use the builtin SSH command of Ansible, +which we override with our wrapper, but some other mechanism we can't hook into. +This is for example the case of the network_cli module of Ansible, which underneath uses Paramiko, +a Python library to handle SSH connections, which prevents our wrapper to be used (see +this GitHub issue for more information).

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/genindex.html b/genindex.html new file mode 100644 index 0000000..8298d98 --- /dev/null +++ b/genindex.html @@ -0,0 +1,2166 @@ + + + + + + Index — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + +
+ + +
+ +
+
+
+
    +
  • »
    • +
  • Index
    • +
  • +
    • +
+
+
+
+
+ + +

Index

+ +
+ Symbols + | A + | B + | C + | G + | I + | M + | N + | P + | R + | S + | W + +
+

Symbols

+ + + +
+ +

A

+ + + +
+ +

B

+ + + +
+ +

C

+ + +
+ +

G

+ + + +
+ +

I

+ + + +
+ +

M

+ + +
    +
  • + mtr command line option + +
    • +
+ +

N

+ + +
+ +

P

+ + +
+ +

R

+ + + +
+ +

S

+ + + +
+ +

W

+ + + +
+ + + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/index.html b/index.html new file mode 100644 index 0000000..4259387 --- /dev/null +++ b/index.html @@ -0,0 +1,439 @@ + + + + + + + Welcome to The Bastion documentation! — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Welcome to The Bastion documentation!

+
+

Warning

+

This documentation is in a WIP status, some edges might be rough!

+
+
+

Wait, what's a bastion exactly? (in 140-ish characters)

+

A so-called bastion is a machine used as a single entry point by operational teams (such as sysadmins, developers, devops, database admins, etc.) to securely connect to other machines of an infrastructure, usually using ssh.

+

The bastion provides mechanisms for authentication, authorization, traceability and auditability for the whole infrastructure.

+
+

Just yet another SSH relayhost/jumphost/gateway?

+

No, The Bastion is an entirely different beast.

+

The key technical difference between those and The Bastion is that it strictly stands between you and the remote server, operating a protocol break in the process, which enables unique features such as tty recording, proper access auditability, builtin access and groups management commands, delegation of responsibilities all the way through, etc.

+

Advanced uses even include doing other things than just SSHing to a remote server.

+

Those wouldn't be possible with a "simple" jumphost. More technical details on the difference here.

+
+
+
+

OK, tell me more!

+

This documentation is organized in several sections. The first one is a PRESENTATION of the main functionalities, principles, and use cases of the bastion.

+

The second section explains the INSTALLATION procedure, including how to set up a quick playground using Docker if you want to get your hands dirty quickly.

+

The third section focuses on the USAGE of the bastion, from the perspective of the different roles, such as bastion users, group owners, bastion admins, etc.

+

The fourth section is about the proper ADMINISTRATION of the bastion itself. If you're about to be the person in charge of managing the bastion for your company, you want to read that one carefully!

+

The fifth section is about DEVELOPMENT and how to write code for the bastion. If you'd like to contribute, this is the section to read!

+

The sixth section is the complete reference of all the PLUGINS that are the commands used to interact with the bastion accounts, groups, accesses, credentials, and more.

+

The unavoidable and iconic FAQ is also available under the PRESENTATION section.

+
+

Presentation

+ +
+
+

Installation

+ +
+
+

Usage

+ +
+
+

Administration

+ +
+
+

Development

+ +
+
+

Plugins

+ +
+
+
+

Indices and tables

+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/installation/advanced.html b/installation/advanced.html new file mode 100644 index 0000000..104c7c1 --- /dev/null +++ b/installation/advanced.html @@ -0,0 +1,610 @@ + + + + + + + Advanced Installation — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Advanced Installation

+

This section goes further in explaining how to setup your bastion. +You should have completed the basic installation first.

+
+

Encryption & signature GPG keys

+
+

Note

+

This section is a prequisite to both the Rotation, encryption & backup of ttyrec files and the +Configuring keys, accounts & groups remote backup steps further down this documentation

+
+

There are 2 pairs of GPG keys being used by the bastion:

+
    +

  • The bastion GPG key

    +
      +

    • The private key is used by the bastion to sign the ttyrec files

      • +

    • The public key is used by the admins to verify the signature and prove +non-repudiation and non-tampering of the ttyrec files

      • +
    +
    • +

  • The admins GPG key

    +
      +

    • The public key is used by the bastion to encrypt the backups and the ttyrec files

      • +

    • The private key is used by the admins to decrypt the backups when +a restore operation is needed, and the ttyrec files

      • +
    +
    • +
+
+

Generating the bastion GPG key

+

Generate a GPG key that will be used by the bastion to sign files, +this might take a while especially if the server is idle:

+
 /opt/bastion/bin/admin/setup-gpg.sh --generate
+
+ gpg: directory `/root/.gnupg' created
+ gpg: Generating GPG key, it'll take some time.
+
+ Not enough random bytes available.  Please do some other work to give
+ the OS a chance to collect more entropy! (Need 39 more bytes)
+ ..........+++++
+ gpg: /root/.gnupg/trustdb.gpg: trustdb created
+ gpg: key A4480F26 marked as ultimately trusted
+ gpg: done
+ gpg: checking the trustdb
+ gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
+ gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
+
+ Configuration file /etc/bastion/osh-encrypt-rsync.conf.d/50-gpg-bastion-key.conf updated:
+ 8<---8<---8<---8<---8<---8<--
+ # autogenerated with /opt/bastion/bin/admin/setup-gpg.sh at Wed Mar 21 10:03:08 CET 2018
+ {
+     "signing_key_passphrase": "************",
+     "signing_key": "5D3CFDFFA4480F26"
+ }
+ --->8--->8--->8--->8--->8--->8
+
+ Done.
+
+
+

While it's working, you can proceed to the section below.

+
+
+

Generating and importing the admins GPG key

+

You should import on the bastion one or more public GPG keys that'll be used for encryption. +If you don't already have a GPG key for this, you can generate one. As this is the admin GPG key, +don't generate it on the bastion itself, but on the desk of the administrator (you?) instead.

+

If you're running a reasonably recent GnuPG version (and the bastion does, too), +i.e. GnuPG >= 2.1.x, then you can generate an Ed25519 key by running:

+
 myname='John Doe'
+ email='jd@example.org'
+ bastion='mybastion4.example.org'
+ pass=$(pwgen -sy 12 1)
+ echo "The passphrase for the key will be: $pass"
+ gpg --batch --pinentry-mode loopback --passphrase-fd 0 --quick-generate-key "$myname <$email>" ed25519 sign 0 <<< "$pass"
+ fpr=$(gpg --list-keys "$myname <$email>" | grep -Eo '[A-F0-9]{40}')
+ gpg --batch --pinentry-mode loopback --passphrase-fd 0 --quick-add-key "$fpr" cv25519 encr 0 <<< "$pass"
+
+ gpg: key 3F379CA7ECDF0537 marked as ultimately trusted
+ gpg: directory '/home/user/.gnupg/openpgp-revocs.d' created
+ gpg: revocation certificate stored as '/home/user/.gnupg/openpgp-revocs.d/3DFB21E3857F562A603BD4F83F379CA7ECDF0537.rev'
+
+
+

If you or the bastion is using an older version of GnuPG, or you are unsure and/or prefer compatibility +over speed or security, you can fallback to an RSA 4096 key:

+
 myname='John Doe'
+ email='jd@example.org'
+ bastion='mybastion4.example.org'
+ pass=`pwgen -sy 12 1`
+ echo "The passphrase for the key will be: $pass"
+ printf "Key-Type: RSA\nKey-Length: 4096\nSubkey-Type: RSA\nSubkey-Length: 4096\n" \
+   "Name-Real: %s\nName-Comment: %s\nName-Email: %s\nExpire-Date: 0\n" \
+   "Passphrase: %s\n%%echo Generating GPG key\n%%commit\n%%echo done\n" \
+   "$myname ($bastion)" $(date +%Y) "$email" "$pass" | gpg --gen-key --batch
+
+ The passphrase for the key will be: ************
+ gpg: Generating GPG key
+
+ Not enough random bytes available.  Please do some other work to give
+ the OS a chance to collect more entropy! (Need 119 more bytes)
+ .....+++++
+
+ gpg: key D2BDF9B5 marked as ultimately trusted
+ gpg: done
+
+
+

Of course, in both snippets above, adjust the myname, email and bastion variables accordingly. +Write down the passphrase in a secure vault. All bastions admins will need it if they are to decrypt ttyrec files +later for inspection, and also decrypt the backup should a restore be needed. +When the key is done being generated, get the public key with:

+
gpg -a --export "$myname <$email>"
+
+
+

Copy it to your clipboard, then back to the bastion, paste it at the following prompt:

+
 /opt/bastion/bin/admin/setup-gpg.sh --import
+
+
+

Also export the private admins GPG key to a secure vault (if you want the same key to be shared by the admins):

+
 gpg --export-secret-keys --armor "$myname <$email>"
+
+
+
+
+
+

Rotation, encryption & backup of ttyrec files

+
+

Note

+

The above section Encryption & signature GPG keys is a prerequisite to this one

+
+

The configuration file is located in /etc/bastion/osh-encrypt-rsync.conf. +You can ignore the signing_key, signing_key_passphrase and recipients options, +as these have been auto-filled when you generated the GPG keys, by dropping configuration files +in the /etc/bastion/osh-encrypt-rsync.conf.d directory. +Any file there takes precedence over the global configuration file.

+

Once you are done with your configuration, you might want to test it by running:

+
/opt/bastion/bin/cron/osh-encrypt-rsync.pl --config-test
+
+
+

Or even go further by starting the script in dry-run mode:

+
/opt/bastion/bin/cron/osh-encrypt-rsync.pl --dry-run
+
+
+
+
+

Configuring keys, accounts & groups remote backup

+
+

Note

+

The above section Encryption & signature GPG keys is a prerequisite to this one, otherwise your backups will NOT +be automatically encrypted, which is something you probably want to avoid.

+
+

Everything that is needed to restore a bastion from backup (keys, accounts, groups, etc.) is backed up daily +in /root/backups by default.

+

If you want to push these backups to a remote location, which is warmly advised, +you have to specify the remote location to scp the backup archives to. +The configuration file is /etc/bastion/osh-backup-acl-keys.conf, +and you should specify the PUSH_REMOTE and PUSH_OPTIONS.

+

To verify that the script is correctly able to connect remotely (and also validate the remote hostkey), +start the script manually:

+
 /opt/bastion/bin/cron/osh-backup-acl-keys.sh
+
+ Pushing backup file (/root/backups/backup-2020-05-25.tar.gz.gpg) remotely...
+ backup-2020-05-25.tar.gz.gpg
+ 100%   21MB  20.8MB/s   00:00
+
+
+

Also verify that the extension is .gpg, as seen above, +which indicates that the script successfully encrypted the backup.

+
+
+

Logs/Syslog

+

It is advised to use syslog for The Bastion application logs. +This can be configured in /etc/bastion/bastion.conf with the parameter enableSyslog.

+

There is a default syslog-ng configuration provided, if you happen to use it. +The file can be found as etc/syslog-ng/conf.d/20-bastion.conf.dist in the repository. +Please read the comments in the file to know how to integrate it properly in your system.

+
+
+

Clustering (High Availability)

+

The bastions can work in a cluster, with N instances. In that case, there is one master instance, +where any modification command can be used (creating accounts, deleting groups, granting accesses), +and N-1 slave instances, where only readonly actions are permitted. Any of these instances may be +promoted, should the need arise.

+

Note that any instance can be used to connect to infrastructures, so in effect all instances can always be used +at the same time. You may set up a DNS round-robin hostname, with all the instances IPs declared, +so that clients automatically choose a random instance, without having to rely on another external component +such as a load-balancer. Note that if you do this, you'll need all the instances to share the same SSH host keys.

+

Before setting up the slave instance, you should have the two bastions up and running +(follow the normal installation documentation). Then, to set up the synchronization between the +instances, proceed as explained below.

+
+

Allowing the master to connect to the slave

+

On the slave, set the readOnlySlaveMode option in the /etc/bastion/bastion.conf file to true:

+
+
run this on the SLAVE:
+
vim /etc/bastion/bastion.conf
+
+
+
+

This will instruct this bastion instance to deny any modification plugin, +so that changes can only be done through the master.

+

Then, append the master bastion synchronization public SSH keyfile, +found in ~root/.ssh/id_master2slave.pub on the master instance, +to ~bastionsync/.ssh/authorized_keys on the slave, +with the following prefix: from="IP.OF.THE.MASTER",restrict

+

Hence the file should look like this:

+
+
run this on the SLAVE:
+
cat ~bastionsync/.ssh/authorized_keys
+from="198.51.100.42",restrict ssh-ed25519 AAA[...]
+
+
+
+
+
+

Pushing the accounts and groups files to the slave

+

Check that the key setup has been done correctly by launching the following command under the root account:

+
+
run this on the MASTER:
+
rsync -v --rsh "ssh -i /root/.ssh/id_master2slave" /etc/passwd /etc/group bastionsync@IP.OF.THE.SLAVE:/root/
+group
+passwd
+
+sent 105,512 bytes  received 8,046 bytes  75,705.33 bytes/sec
+total size is 1,071,566  speedup is 9.44
+
+
+
+

If this works correctly, you'll have two new files in the /root directory of the slave instance. +We'll need those for the next step, which is verifying that the UIDs/GIDs of the slave instance are matching +the master instance's ones. Indeed, the sync of the /etc/passwd and /etc/group files can have adverse effects +on a newly installed machine where the packages were not installed in the same order than on the master, hence having +possibly mismatching UIDs/GIDs for the same users/groups.

+

The next step ensures these are matching between the master and the slave before actually enabling the synchronization.

+
+
+

Ensuring the UIDs/GIDs are in sync

+

Now that we have the master's /etc/passwd and /etc/group files in the slave's /root folder, +we can use a helper script to check for the UIDs/GIDs matches between the master and the slave. +This script's job is to check whether there is any discrepancy, and if this is the case, generate another script, +tailored to your case, to fix them:

+
+
run this on the SLAVE:
+
/opt/bastion/bin/admin/check_uid_gid_collisions.pl --master-passwd /root/passwd --master-group /root/group --output /root/syncids.sh
+WARN: local orphan group: local group 50 (with name 'staff') is only present locally, if you want to keep it, create it on the master first or it'll be erased
+
+There is at least one warning, see above.
+If you want to handle them, you may still abort now.
+Type 'YES' to proceed regardless.
+
+
+
+

In the example above, the script warns us that some accounts or groups are only existing on the slave instance, +and not at all on the master. In this case, it's up to you to know what you want to do. If you choose to ignore it, +these accounts and groups will be erased on the first synchronization, as the master will push its own accounts and +groups to the slave instance. Such a discrepancy shouldn't happen as long as you're using the same OS and distro +on both sides. It may happen if you have installed more packages on the slave instance than on the master, as some +packages also create system groups or accounts. A possible fix is to install the same packages on the master, and/or +simply adding the account(s) and/or group(s) on the master, so that they're synchronized everywhere.

+

If you type 'YES' or simply don't have any warnings, you should see something like this:

+
+
(output continued)
+
Name collision on UID: master UID 38 exists on local but with a different name (master=gnats local=list)
+-> okay, offsetting local UID 38 to 50000038
+Differing name attached to same UID: master UID 38 doesn't exist on local, but its corresponding name 'gnats' does, with local UID 41
+Name collision on UID: master UID 39 exists on local but with a different name (master=list local=irc)
+-> okay, offsetting local UID 39 to 50000039
+[...]
+You may now review the generated script (/root/syncids.sh) and launch it when you're ready.
+Note that you'll have to reboot once the script has completed.
+
+
+
+

The generated script is found at the location you've specified, which is /root/syncids.sh if you used +the command-line we suggested above. Reviewing this script is important, as this is the one that will be making +UIDs/GIDs modification to your slave instance, as to sync them to the master's ones, including propagating these +changes on your filesystem, using chmod and chgrp commands.

+

Once you're ready (note that you'll have to reboot the slave right after), you may run the generated script:

+
+
run this on the SLAVE:
+
bash /root/syncids.sh
+
+We'll change the UIDs/GIDs of files, when needed, in the following mountpoints: / /home /run /run/lock /run/snapd/ns /run/user/1001 /run/user/1001/doc /run/user/1001/gvfs
+If you'd like to change this list, please edit this script and change the 'fslist' variable in the header.
+Otherwise, if this sounds reasonable (e.g. there is no remotely mounted filesystem that you don't want us to touch), say 'YES' below:
+
+
+
+

Please review the listed mountpoints (obviously, they'll be different than the ones above). As stated you may +edit the script to adjust them if needed. If any UID/GID needs to be changed to be in sync with the master, +the script will ensure the changes are propagated to the specified filesystems. You might want to exclude +network-mounted filesystems and such, if any. The script does its best to do this for you, but you should ensure +that it has got it right.

+

Then, the script may list the daemons and running processes that it'll need to kill before doing the changes, +as Linux forbids changing UIDs/GIDs when they're used by a process. This is why a reboot is needed at the end.

+
+
(output continued)
+
The following processes/daemons will need to be killed before swapping the UIDs/GIDs:
+USER         PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
+kernoops    2484  0.0  0.0  11264   440 ?        Ss   Apr11   0:04 /usr/sbin/kerneloops
+whoopsie    2467  0.0  0.0 253440 11860 ?        Ssl  Apr11   0:00 /usr/bin/whoopsie -f
+colord      2227  0.0  0.0 249220 13180 ?        Ssl  Apr11   0:00 /usr/libexec/colord
+geoclue     2091  0.0  0.1 905392 20268 ?        Ssl  Apr11   1:09 /usr/libexec/geoclue
+rtkit       1789  0.0  0.0 153156  2644 ?        SNsl Apr11   0:00 /usr/libexec/rtkit-daemon
+syslog      1445  0.0  0.0 224548  4572 ?        Ssl  Apr11   0:02 /usr/sbin/rsyslogd -n -iNONE
+systemd+    1305  0.0  0.0  91016  4088 ?        Ssl  Apr11   0:00 /lib/systemd/systemd-timesyncd
+
+If you want to stop them manually, you may abort now (CTRL+C) and do so.
+Press ENTER to continue.
+
+
+
+

As stated, ensure that it's alright that these daemons are killed. You may want to terminate them manually +if needed, otherwise the script will simply send a SIGTERM to these processes.

+
+
(output continued)
+
[...]
+Restoring SUID/SGID flags where needed...
+[...]
+UID/GID swapping done, please reboot now.
+
+
+
+

As instructed, you may now reboot.

+
+

Note

+

If you're currently restoring from a backup, you may stop here and resume +the Restoring from backup procedure.

+
+
+
+

Enabling the synchronization

+

Now that the master and the slave UIDs/GIDs are matching, we may enable the synchronization daemon:

+
+
run this on the MASTER:
+
vim /etc/bastion/osh-sync-watcher.sh
+
+
+
+

You may review the configuration, but the two main items to review are:

+
    +

  • enabled, which should be set to 1

    • +

  • remotehostlist, which should contain the hosts/IPs list of the slave instances, separated by spaces

    • +
+

If the synchronization daemon was not already enabled and started (i.e. this is the first slave instance +you're setting up for this master), then you should configure it to start it on boot, and you may also +start it manually right now:

+
+
run this on the MASTER:
+
systemctl enable osh-sync-watcher
+systemctl start osh-sync-watcher
+
+
+
+

Otherwise, if the daemon is already enabled and active, you can just restart it so it picks up the new configuration:

+
+
run this on the MASTER:
+
systemctl restart osh-sync-watcher
+
+
+
+

Now, you can check the logs (if you configured syslog instead, which is encouraged, +then the logfile depends on your syslog daemon configuration. If you're using our bundled syslog-ng +configuration, the output is logged in /var/log/bastion/bastion-scripts.log)

+
+
run this on the MASTER:
+
tail -F /var/log/bastion/osh-sync-watcher.log
+Apr 12 18:11:25 bastion1.example.org osh-sync-watcher.sh[3346532]: Starting sync!
+Apr 12 18:11:25 bastion1.example.org osh-sync-watcher.sh[3346532]: 192.0.2.42: [Server 1/1 - Step 1/3] syncing needed data...
+Apr 12 18:11:27 bastion1.example.org osh-sync-watcher.sh[3346532]: 192.0.2.42: [Server 1/1 - Step 1/3] sync ended with return value 0
+Apr 12 18:11:27 bastion1.example.org osh-sync-watcher.sh[3346532]: 192.0.2.42: [Server 1/1 - Step 2/3] syncing lastlog files from master to slave, only if master version is newer...
+Apr 12 18:11:28 bastion1.example.org osh-sync-watcher.sh[3346532]: 192.0.2.42: [Server 1/1 - Step 2/3] sync ended with return value 0
+Apr 12 18:11:28 bastion1.example.org osh-sync-watcher.sh[3346532]: 192.0.2.42: [Server 1/1 - Step 3/3] syncing lastlog files from slave to master, only if slave version is newer...
+Apr 12 18:11:30 bastion1.example.org osh-sync-watcher.sh[3346532]: 192.0.2.42: [Server 1/1 - Step 3/3] sync ended with return value 0
+Apr 12 18:11:39 bastion1.example.org osh-sync-watcher.sh[3346532]: All secondaries have been synchronized successfully
+Apr 12 18:11:39 bastion1.example.org osh-sync-watcher.sh[3346532]: Watching for changes (timeout: 120)...
+
+
+
+

Your new slave instance is now ready!

+
+
+
+

Creating SSHFP DNS records

+

If you want to use SSHFP to help authenticating your bastion public keys by publishing their checksum +in your DNS, here is now to generate the correct records:

+
awk 'tolower($1)~/^hostkey$/ {system("ssh-keygen -r bastion.name -f "$2)}' /etc/ssh/sshd_config
+
+
+

You shall then publish them in your DNS. It is also a good idea to secure your DNS zone with DNSSEC, +but this is out of the scope of this manual.

+
+
+

Hardening the SSH configuration

+

Using our SSH templates is a good start in any case. If you want to go further, there are a lot of online resources +to help you harden your SSH configuration, and audit a running SSHd server. +As the field evolves continuously, we don't want to recommend one particularly here, +as it might get out of date rapidly, but looking for ssh audit on GitHub +is probably a good start. Of course, this also depends on your environment, and you might not be able to harden +your SSHd configuration as much as you would like.

+

Note that for The Bastion, both sides can be independently hardened: +the ingress part is handled in sshd_config, and the egress part is handled in ssh_config.

+
+
+

2FA root authentication

+

The bastion supports TOTP (Time-based One Time Password), to further secure high profile accesses. +This section covers the configuration of 2FA root authentication on the bastion itself. +TOTP can also be enabled for regular bastion users, but this is covered in another section. +To enable 2FA root authentication, run on the bastion:

+
script -c "google-authenticator -t -Q UTF8 -r 3 -R 15 -s /var/otp/root -w 2 -e 4 -D" /root/qrcode
+
+
+

Of course, you can check the --help and adjust the options accordingly. +The example given above has sane defaults, but you might want to adjust if needed. +Now, flash this QR code with your phone, using a TOTP application. +You might want to copy the QR code somewhere safe in case you need to flash it on some other phone, +by exporting the base64 version of it:

+
gzip -c /root/qrcode | base64 -w150
+
+
+

Copy this in your password manager (for example). You can then delete the /root/qrcode file.

+

You have then two configuration adjustments to do.

+
    +

  • First, ensure you have installed the provided /etc/pam.d/sshd file, or at least the corresponding line +to enable the TOTP pam plugin in your configuration.

    • +

  • Second, ensure that your /etc/ssh/sshd_config file calls PAM for root authentication. +In the provided templates, there is a commented snippet to do it. The uncommented snippet looks like this:

    • +
+
# 2FA has been configured for root, so we force pubkey+PAM for it
+Match User root
+    AuthenticationMethods publickey,keyboard-interactive:pam
+
+
+

Note that first, the usual publickey method will be used, then control will be passed to PAM. +This is where the /etc/pam.d/sshd configuration will apply.

+

Now, you should be asked for the TOTP the next time you try to login through ssh as root. +In case something goes wrong with the new configuration, be sure to keep your already opened existing +connection to be able to fix the problem without falling back to console access.

+

Once this has been tested, you can (and probably should) also protect the direct root console access +to your machine with TOTP, including a snippet similar to this one:

+
# TOTP config
+auth    [success=1 default=ignore]  pam_google_authenticator.so secret=/var/otp/${USER}
+auth    requisite                   pam_deny.so
+# End of TOTP Config
+
+
+

inside your /etc/pam.d/login file.

+

Of course, when using TOTP, this is paramount to ensure your server is properly synchronized through NTP.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/installation/basic.html b/installation/basic.html new file mode 100644 index 0000000..9682c53 --- /dev/null +++ b/installation/basic.html @@ -0,0 +1,381 @@ + + + + + + + Basic Installation — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Basic Installation

+

If you are just upgrading from a previous version, please read upgrading instead.

+
+

0. Got Puppet?

+

We published a Puppet module to handle The Bastion configuration and prerequisites. +The GitHub repo is here and our module has been published to +the Puppet forge. +Of course, its usage is completely optional, but if you choose to use it, +some of the below steps will be done by Puppet. Hence, you might want to only consider the following steps:

+ +
+
+

1. Operating system

+
+

Warning

+

The Bastion expects to be the only main service running on the server, +please see this FAQ entry for more information.

+
+

The following Linux distros are tested with each release, but as this is a security product, +you are warmly advised to run it on the latest up-to-date stable version of your favorite OS:

+
    +

  • Debian 12 (Bookworm), 11 (Bullseye), 10 (Buster)

    • +

  • RockyLinux 8.x, 9.x

    • +

  • Ubuntu LTS 24.04, 22.04, 20.04, 18.04

    • +

  • OpenSUSE Leap 15.6*

    • +
+

*: Note that these versions have no out-of-the-box MFA support, as they lack packaged versions of pamtester, +pam-google-authenticator, or both. Of course, you may compile those yourself. +Any other so-called modern Linux version are not tested with each release, +but should work with no or minor adjustments.

+

The following OS are also tested with each release:

+
    +

  • FreeBSD/HardenedBSD 13.2**

    • +
+

**: Note that these have partial MFA support, due to their reduced set of available pam plugins. +Support for either an additional password or TOTP factor can be configured, but not both at the same time. +The code is actually known to work on FreeBSD/HardenedBSD 10+, but it's only regularly tested under 13.2.

+

Other BSD variants, such as OpenBSD and NetBSD, are unsupported as they have a severe limitation over the maximum +number of supplementary groups, causing problems for group membership and restricted commands checks, +as well as no filesystem-level ACL support and missing PAM support (hence no MFA).

+

In any case, you are expected to install this on a properly secured machine (including, but not limited to: +iptables/pf, reduced-set of installed software and daemons, general system hardening, etc.). +If you use Debian, following the CIS Hardening guidelines is +a good start. We have a tool to check for compliance against these guidelines. +If you use Debian and don't yet have your own hardened template, this script should help you getting up to speed, +and ensuring your hardened host stays hardened over time, through a daily audit you might want to setup through cron.

+

Great care has been taken to write secure, tested code, but of course this is worthless if your machine +is a hacker highway. Ensuring that all the layers below the bastion code (the operating system +and the hardware it's running on) is your job.

+
+
+

2. Connect to your server as root

+

You'll need to be connected to your server as root to perform the installation. If you're using root password +authentication through SSH to do so, note that during the installation, as the SSH server configuration +will be hardened, the SSH password authentication will be disabled server-wide.

+

Hence, to access your server, please set up an SSH public key authentication instead of a password authentication, +and do so before proceeding with the next steps. Otherwise you might lose access to your own server once the +SSH hardening will be in effect, as password authentication will then be disabled.

+
+
+

3. Get the code

+

The bastion code usually lives under /opt/bastion. +You can either use git clone directly, or get the tarball of the latest release.

+
    +

  • Using git:

    • +
+
git clone https://github.com/ovh/the-bastion /opt/bastion
+git -C /opt/bastion checkout $(git -C /opt/bastion tag | tail -1)
+
+
+
    +

  • Using the tarball:

    • +
+

Get the tarball of the latest release, which can be found +there, then untar it:

+
mkdir -p /opt/bastion
+tar -C /opt/bastion -zxf v3.16.99-rc2.tar.gz
+
+
+

The code supports being hosted somewhere else on the filesystem hierarchy, but this is discouraged as you might +need to adjust a lot of configuration files (notably sudoers.d, cron.d, init.d) that needs an absolute path. +You should end up with directories such as bin, lib, etc. directly under /opt/bastion.

+
+
+

4. Install the needed packages

+

For the supported Linux distros (see above), you can simply run:

+
/opt/bastion/bin/admin/packages-check.sh -i
+
+
+

You can add other parameters to install optional packages, depending on your environment:

+
    +

  • -s to install syslog-ng (advised, we have templates files for it)

    • +

  • -d to install packages needed for developing the software (useless in production)

    • +
+

You'll also need our version of ttyrec, ovh-ttyrec. +To get and install the precompiled binary that will work for your OS and architecture, you can use this script:

+
/opt/bastion/bin/admin/install-ttyrec.sh -a
+
+
+

This will detect your distro, then download and either install the .deb or .rpm package +for ovh-ttyrec. If your distro doesn't handle those package types, +it'll fallback to installing precompiled static binaries. +Of course you can package it yourself and make it available to your own internal repositories instead of installing it this way.

+

If you plan to use the PIV functionalities of The Bastion, +you'll also need to install the yubico-piv-checker helper tool.

+

You may also want to install the-bastion-mkhash-helper tool +if you want to be able to generate so-called type 8 and type 9 password hashes.

+
/opt/bastion/bin/admin/install-yubico-piv-checker.sh -a
+/opt/bastion/bin/admin/install-mkhash-helper.sh -a
+
+
+
+
+

5. Encrypt /home

+

Strictly speaking, this step is optional, but if you skip it, know that all the SSH private keys and session +recordings will be stored unencrypted on the /home partition. +Of course, if partition encryption is already handled by the OS template you use, +or if the storage layer of your OS is encrypted by some other mean, you may skip this section.

+

First, generate a secure password on your desk (but not too complicated so it can be typed +on a console over your hypervisor over a VDI over VPN over 4G in the dark at 3am on a Sunday) +and save it to a secure location: pwgen -s 10.

+

Then you can use the helper script to do this, it'll guide you through the process. +When prompted for a passphrase, enter the one chosen just before:

+
/opt/bastion/bin/admin/setup-encryption.sh
+
+
+

If you get a cryptsetup error, you might need to add --type luks1 to the cryptsetup luksFormat command +in the script. It can happen if your kernel doesn't have the necessary features enabled for LUKS2.

+
+

Warning

+

Once you have setup encryption, do not forget to ensure that the keys backup script has encryption enabled, +otherwise the backups will be stored unencrypted in /root/backups, +which would make your /home encryption moot. +This is not covered here because you can do it later, just don't forget it: +it's in the advanced installation section.

+
+
+
+

6. Setup bastion and system configuration

+

The following script will do that for you. There are several possibilities here.

+
    +

  • If you're installing a new machine (nobody is using it as a bastion yet), then you can regenerate brand new +host keys and directly harden the ssh configuration without any side effect:

    • +
+
/opt/bastion/bin/admin/install --new-install
+
+
+
    +

  • If you're upgrading an existing machine (from a previous version of this software), +and there are already some people using it as a bastion, then if you change the host keys, +they'll have to acknowledge the change when connecting, i.e. this is not transparent at all. +To avoid doing that and not touching either the ssh config or the host keys, use this:

    • +
+
/opt/bastion/bin/admin/install --upgrade
+
+
+

If you used --upgrade, then you are warmly advised to harden the configuration yourself, +using our templates as a basis. For example, if you're under Debian 11:

+
vimdiff /opt/bastion/etc/ssh/ssh_config.debian11 /etc/ssh/ssh_config
+vimdiff /opt/bastion/etc/ssh/sshd_config.debian11 /etc/ssh/sshd_config
+
+
+

There are other templates available in the same directory, for the other supported distros.

+
    +

  • If you want to have a fine-grained control of what is managed by the installation script, +and what is managed by yourself (or any configuration automation system you may have), you can review all the fine-grained options:

    • +
+
/opt/bastion/bin/admin/install --help
+
+
+
+
+

7. Review the configuration

+

Base configuration files have been copied, you should review the main configuration and modify it to your needs:

+
vim /etc/bastion/bastion.conf
+
+
+
+
+

8. Check that the code works on your machine

+

This script will verify that all required modules are installed:

+
/opt/bastion/bin/dev/perl-check.sh
+
+
+
+

Note

+

If you're installing this instance to restore a backup, you may stop here and resume the +standard Restoring from backup procedure.

+
+
+
+

9. Manually create our first bastion account

+

Just launch this script, replacing USERNAME by the username you want to use:

+
/opt/bastion/bin/admin/setup-first-admin-account.sh USERNAME auto
+
+
+

You'll just need to specify the public SSH key to add to this new account. +It'll be created as a bastion admin, and all the restricted commands will be granted.

+
+

Note

+

This command will also give you a so-called bastion alias, this is the command you'll routinely use to +connect to the bastion, and to your infrastructures through it, replacing in effect your previous usage +of the ssh command. The alias name advertised on account creation is configurable in bastion.conf, +and of course the users can rename it as they see fit, but it's advised to keep this command short, +as people will use it a lot.

+
+

If you want to create other admin accounts, you can repeat the operation. +All the other accounts should be created by a bastion admin (or more precisely, +by somebody granted to the accountCreate command), using the bastion own commands. +But more about this in the section Using the bastion.

+

You may head over to the USAGE section on the left menu, but please read the warning below first.

+
+

Warning

+

Note that even if your bastion should now be functional, proper setup for a production-level environment +is not done yet: for example, you don't have any backup system in place! Please ensure you follow the +advanced installation documentation and carely consider each step (by either completing it +or deciding that it's not mandatory for your use case), before considering your installation complete.

+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/installation/docker.html b/installation/docker.html new file mode 100644 index 0000000..7aca664 --- /dev/null +++ b/installation/docker.html @@ -0,0 +1,216 @@ + + + + + + + Sandbox using Docker — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Sandbox using Docker

+

This is a good way to test The Bastion within seconds, but read the FAQ +if you're serious about using containerization in production.

+

The sandbox image is available for the following architectures: linux/386, linux/amd64, linux/arm/v6, +linux/arm/v7, linux/arm64, linux/ppc64le, linux/s390x.

+
    +

  • Let's run the docker image:

    • +
+
docker run -d -p 22 --name bastiontest ovhcom/the-bastion:sandbox
+
+
+
    +

  • Or, if you prefer building the docker image yourself, you can: use the two commands below. +Of course, if you already typed the docker run command above, you can skip the following commands:

    • +
+
docker build -f docker/Dockerfile.debian10 -t bastion:debian10 .
+docker run -d -p 22 --name bastiontest bastion:debian10
+
+
+
    +

  • Configure the first administrator account (get your public SSH key ready)

    • +
+
docker exec -it bastiontest /opt/bastion/bin/admin/setup-first-admin-account.sh poweruser auto
+
+
+
    +

  • We're now up and running with the default configuration! +Let's setup a handy bastion alias, and test the info command:

    • +
+
PORT=$(docker port bastiontest | cut -d: -f2)
+alias bastion="ssh poweruser@127.0.0.1 -tp $PORT -- "
+bastion --osh info
+
+
+
    +

  • It should greet you as being a bastion admin, which means you have access to all commands. +Let's enter interactive mode:

    • +
+
bastion -i
+
+
+
    +

  • This is useful to call several --osh plugins in a row. Now we can ask for help to see all plugins:

    • +
+
$> help
+
+
+
    +

  • If you have a remote machine you want to try to connect to through the bastion, fetch your egress key:

    • +
+
$> selfListEgressKeys
+
+
+
    +

  • Copy this public key to the remote machine's authorized_keys under the .ssh/ folder +of the account you want to connect to, then:

    • +
+
$> selfAddPersonalAccess --host <remote_host> --user <remote_account_name> --port-any
+$> ssh <remote_account_name>@<remote_host>
+
+
+
    +

  • Note that you can connect directly without using interactive mode, with:

    • +
+
bastion <remote_account_name>@<remote_machine_host_or_ip>
+
+
+

That's it! You can head over to the USAGE section on the left menu for more information. +Be sure to check the help of the bastion with bastion --help, +along with the help of each osh plugin with bastion --osh command --help.

+

Also don't forget to customize your bastion.conf file, +which can be found in /etc/bastion/bastion.conf (for Linux).

+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/installation/restoring_from_backup.html b/installation/restoring_from_backup.html new file mode 100644 index 0000000..8171a73 --- /dev/null +++ b/installation/restoring_from_backup.html @@ -0,0 +1,266 @@ + + + + + + + Restoring from backup — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Restoring from backup

+

In this section, we'll detail how to restore a bastion's main data from a backup.

+

This can be useful in two main cases:

+
    +

  • When an account with high privileges has deleted or altered by mistake a great amount of accounts or groups, up +to a point where it's operationally easier to just restore the settings, accounts, groups and keys from the latest +available backup

    • +

  • When you are not in an HA setup and your only +instance is down and can't be brought back up in a timely manner.

    • +
+

Note that if you are in a HA setup and you need to add a new node (regardless of the fact that you're replacing +a failed node or not), you don't need to restore from backup: you can simply follow the HA setup procedure so +that your new node is synced with your main node.

+
+

Prerequisites

+

First, you obviously must have a backup at hand, which should be the case if you followed the +Configuring keys, accounts & groups remote backup section when you first installed the instance you want to restore.

+

If the backup is encrypted with GPG (it should be), you must have access to the corresponding GPG private key and +its passphrase.

+

You must ensure that the new server you're setting up has the same OS release than the one the backup file +comes from, as we'll overwrite the new server's accounts and groups files with the backed up versions. +This could cause adverse effects if the distro or release differ, although the restore script won't stop +you from doing so (it'll even help you adjust the discrepancies if needed, but again, this is strongly discouraged).

+
+
+

Steps

+
+

Installation

+

On the new server you want to deploy the backup to, you must first follow the standard Basic Installation +procedure, up to and including the Check that the code works on your machine step.

+

Once done, you may proceed to the next steps below.

+
+
+

GPG key and backup archive import

+

On the server you've just installed, you'll need to import the private GPG key that was used to encrypt the backup, and +you'll also need to fetch the backup archive itself. It's a good practice to NOT decrypt the backup archive prior to +transferring it to the new server. This way, you're sure that the credentials and keys contained in the backup have +not been compromised.

+

To import the GPG key, just run:

+
gpg --import
+
+
+

And paste the private GPG key corresponding to the backup so that it gets imported into root's keyring.

+

Alternatively, you can put the private GPG key in a temporary file, and import it this way:

+
gpg --import < /tmp/backupkey.asc
+
+
+

You may now import the backup archive, which usually has a name matching the backup-YYYY-MM-DD.tar.gz.gpg format. +You can use scp, sftp or any other method to get this file onto the server, at any location you see fit. We'll use +/root as location for the rest of this documentation, as this is guaranteed to only be readable by root, +hence not compromising the keys and credentials.

+
+
+

Decrypt and extract accounts and groups

+

Now, you can decrypt the backup archive:

+
gpg -d /root/backup-YYYY-MM-DD.tar.gz.gpg > /root/backup-decrypted.tar.gz
+gpg: encrypted with 4096-bit RSA key, ID F50BFFC49143C821, created 2021-03-27
+   "Bastion Administrators <bastions.admins@example.org>"
+
+
+

You'll have to input the GPG private key passphrase when asked to.

+

Then, check whether the archive seems okay:

+
tar tvzf /root/backup-decrypted.tar.gz
+
+
+

You should see a long list of files, most under the /home hierarchy.

+

We now need to extract the backed up /etc/passwd and /etc/group files, to ensure the new +instance we're setting up has its UIDs/GIDs synced with the system we're restoring:

+
tar xvzf /root/backup-decrypted.tar.gz -C /root --strip-components=1 etc/passwd etc/group
+etc/group
+etc/passwd
+
+
+

We now have the two original accounts and groups lists in /root, and we can proceed to check +whether the UIDs and GIDs are in sync.

+
+
+

Ensuring the UIDs/GIDs are in sync

+

This procedure is the same than when setting up a slave instance bastion, +please follow the corresponding step there and come +back to this documentation when it's done.

+
+

Note

+

The referenced step above asks you to reboot at the end, please ensure you've done it before +continuing with the rest of the procedure below.

+
+
+
+

Restoring

+

Now that we know the UIDs/GIDs are synced, we can proceed with the full restore:

+
tar -C / --preserve-permissions --preserve-order --overwrite --acls --numeric-owner -xzvf /root/backup-decrypted.tar.gz
+
+
+
+

Note

+

If you're getting errors such as 'Warning: Cannot acl_from_text: Invalid argument', please ensure that your +filesystem supports ACLs and is mounted with ACL support, otherwise tar can't restore ACLs from the backup.

+
+
+
+

Back to production

+

As the configuration of the SSH daemon has also been restored, you might want to restart it so that it +picks up the new configuration:

+
service ssh restart
+
+
+

Once this is done, all the accounts that were present in the backup should be working. After ensuring this is the case, +you may put the server put back in production.

+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/installation/upgrading.html b/installation/upgrading.html new file mode 100644 index 0000000..1a636f0 --- /dev/null +++ b/installation/upgrading.html @@ -0,0 +1,639 @@ + + + + + + + Upgrading — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Upgrading

+
+

General upgrade instructions

+
    +

  • First, check below if there are specific upgrade instructions for your version.

    • +

  • When you're ready, update the code, if you're using git, you can checkout the latest tag:

    • +
+
( umask 0022 && cd /opt/bastion && git fetch && git checkout $(git tag | tail -1) )
+
+
+
    +

  • Run the install script in upgrade mode, so it can make adjustments to the system needed for the new version:

    • +
+
/opt/bastion/bin/admin/install --upgrade
+
+
+

Note that if you're using an infrastructure automation tool such as Puppet, Ansible, Chef, +and don't want the update script to touch some files that you manage yourself, +you can use --managed-upgrade instead of --upgrade. +See the --help for a more fine-grained upgrade path if needed.

+
+
+

Version-specific upgrade instructions

+
+

v3.16.99-rc2 - 2024/09/17

+

This release drops support for Ubuntu 16.04 and CentOS 7. If you're still using these EOL OS releases (which is +obviously discouraged), proper functioning of The Bastion is no longer tested or guaranteed. +It also adds official support for Ubuntu 24.04 LTS and OpenSUSE Leap 15.6, these were already working but +are now part of the integration tests.

+

This release adds support of wildcards (also called "shell-style globbing characters"), namely ? and *, +when using the --user option for plugins such as groupAddServer, groupDelServer, groupAddGuestAccess, +groupDelGuestAccess, accountAddPersonalAccess, accountDelPersonalAccess, selfAddPersonalAccess, +selfDelPersonalAccess.

+

We also deprecate all the --sftp, --scpdown, --scpup options that are now replaced by a more generic +--protocol option, which supports sftp, scpdown ``, ``scpup and now also rsync as parameters. +The use of rsync is similar to sftp and scp, and is detailed here: rsync.

+

Last but not least, the sntrup761x25519-sha512@openssh.com KEX algorithm is now enabled by default on shipped +versions of sshd_config and ssh_config. If you're upgrading, these files won't be touched, so if you want to +add support, you'll need to modify them manually by prepending sntrup761x25519-sha512@openssh.com to the +KexAlgorithms line. Verify that the OpenSSH version shipped by your OS does support it (run ssh -Q kex).

+
+
+

v3.16.01 - 2024/04/17

+

No specific upgrade instructions.

+
+
+

v3.16.00 - 2024/04/10

+

This version adds support for Secure Keys (FIDO2) for ingress authentication. It requires at least OpenSSH 8.2 +installed on the server hosting The Bastion, as support for FIDO2 was added in this version. +Of the currently supported OS versions, the following are known to have a recent-enough version:

+
    +

  • Debian 11

    • +

  • Debian 12

    • +

  • Ubuntu 20.04

    • +

  • Ubuntu 22.04

    • +

  • OpenSUSE Leap 15.5

    • +

  • Rocky Linux 9

    • +
+

Note that if you are upgrading, you'll need to enable the new ingress algorithms in the /etc/bastion/bastion.conf +file, under the allowedIngressSshAlgorithms option. You may want to add ecdsa-sk and ed25519-sk to the list +if you want to support the FIDO2-backed versions of these two algorithms. +You may also refer to the distributed default configuration file in etc/bastion/bastion.conf.dist, +which enables them by default.

+
+
+

v3.15.00 - 2024/03/22

+

No specific upgrade instructions.

+
+
+

v3.14.16 - 2024/02/20

+

No specific upgrade instructions.

+
+
+

v3.14.15 - 2023/11/08

+

This release fixes the CVE-2023-45140 with severity 4.8 (CVSS V3). +Please refer to its page for impact and mitigation details.

+

The changes introduced to fix this vulnerability imply that if you're using the scp or sftp plugins, +you'll need to update your wrappers using the new versions provided by this release. The old helpers will still +work, but only for remote hosts that don't require MFA.

+

To get the new wrappers for your account on a given bastion, just call --osh scp or --osh sftp without +specifying any host, which will give you your script, and examples of use. +As you'll notice, the new scripts are no longer helpers (that were to be used through scp -S and +sftp -S), but wrappers, that will call scp and sftp themselves.

+

As outlined above, the old helpers will still work for the foreseeable future, but as they're not able to +request MFA when this is configured for a remote host, they'll simply fail for such hosts on an updated +version of the bastion.

+

If you have some accounts that use automated accesses through the bastion and use scp or sftp on +hosts that have JIT MFA configured through their group, you'll need to set these accounts as immune to JIT MFA, +which can be done through accountModify's --mfa-password-required bypass +and/or accountModify --mfa-totp-required bypass, as has always been the case for classic SSH access.

+

An HMAC shared secret is automatically generated when this release is deployed, this secret must be shared +by all the instances of the same cluster. Hence, you should start by deploying this release on the primary +node, which will generate the secret automatically during the standard upgrading procedure, so that this +node can push the shared-secret to the other nodes. The other nodes don't have to be upgraded beforehand, +they'll just not use the secret until they're upgraded to this version, and JIT MFA for scp and sftp +will not work through them until this is the case.

+

Once the primary node is upgraded, you should ensure the new file containing the HMAC shared secret is part +of the synchronization list. If you did not customize your synchronization list, you can apply the new one +over the old one directly:

+
cat /opt/bastion/etc/bastion/osh-sync-watcher.rsyncfilter.dist > /etc/bastion/osh-sync-watcher.rsyncfilter
+
+
+

Then, you need to restart the synchronization daemon, so that it takes into consideration the new file +(containing the shared secret) to push to the other nodes. This is usually done this way:

+
systemctl restart osh-sync-watcher
+
+
+

You can verify on the other nodes that the /etc/bastion/mfa-token.conf file is now present.

+
+
+

v3.14.00 - 2023/09/19

+

A new helper is required to support the so-called "type 8" and "type 9" password hash types, used on some +network devices. This helper is optional, and these hashes types will simply not be generated if the helper is +missing. The plugins concerned by this change are selfGeneratePassword, selfListPasswords, +accountGeneratePassword, accountListPasswords, groupGeneratePassword, groupListPasswords.

+

New installations will get this helper installed automatically. When upgrading, if you'd like to install +this helper, you'll need to install it by running the following command as root:

+
/opt/bastion/bin/admin/install-mkhash-helper.sh -a
+
+
+

This will detect your OS and either install a .deb file, an .rpm file, or a static binary.

+

If you want to ensure that the helper has installed correctly, you can call it manually for testing purposes:

+
echo test | the-bastion-mkhash-helper
+{"Type8":"$8$EpvF1cVVzoEQFE$L3ZBWzfH9MTPo4WLX29Jd8LTM5sKlfEjtRZ//XMys2U","Type9":"$9$yRlXzt0T7WBs3E$YdKk8WMvLvAVcbglx.bMZoRlwBa6l5EhwLhBh1o0u4g","PasswordLen":4}
+
+
+

If you're not generating passwords for use with network devices using type 8 or type 9 hash types, installation of this +helper is not required.

+
+
+

v3.13.01 - 2023/08/22

+

No specific upgrade instructions.

+
+
+

v3.13.00 - 2023/07/28

+

Plugins output is now recorded using ttyrec, as the connections are, instead of being stored in sqlite format +within the home folder of the account. This helps avoiding the sqlite databases growing too much in size when +accounts are using osh commands very intensively.

+
+
+

v3.12.00 - 2023/06/27

+

Support for Debian 9 has been dropped. This doesn't mean that the code will suddenly stop working under this version, +but that tests no longer include this OS. Please consider upgrading to a more recent OS, as ensuring the underlying +OS is up to date and still supported is paramount to the security of The Bastion (or any other software).

+

Support of Debian "Bookworm" 12 is now official, as this is now Debian stable.

+
+
+

v3.11.02 - 2023/04/18

+

No specific upgrade instructions.

+
+
+

v3.11.01 - 2023/03/27

+

No specific upgrade instructions.

+
+
+

v3.11.00 - 2023/03/23

+

The upgrade path from the preceding version is straightforward, however there is a change +that you might want to be aware of before hitting the upgrade button:

+

The previously implicitly assumed --port-any and --user-any options +to the (self|account)(Add|Del)PersonalAccess commands, when either --user or --port were omitted, +now require to be stated explicitly, to be consistent with the behaviour of group(Add|Del)Server, +which always required it. Note that using this mechanism always emitted a deprecation warning, +since the first publicly released version, encouraging the explicit use of --user-any and/or --port-any +when this was desired. Now, omitting these options will simply return an error, +as this has always been the case with group(Add|Del)Server.

+

Example of previous behaviour:

+
$ bssh --osh selfAddPersonalAccess --host 127.0.0.5 --force
+╭──ac777d06bec9───────────────────────────────────────────the-bastion-3.10.00───
+│ ▶ adding personal access to a server on your account
+├───────────────────────────────────────────────────────────────────────────────
+│ ❗ You didn't specify --user or --user-any, defaulting to --user-any, this will no longer be implicit in future versions
+│ ❗ You didn't specify --port or --port-any, defaulting to --port-any, this will no longer be implicit in future versions
+│ Forcing add as asked, we didn't test the SSH connection, maybe it won't work!
+│ Access to 127.0.0.5 was added to account jdoe
+╰────────────────────────────────────────────────────</selfAddPersonalAccess>───
+
+
+

Example of new behaviour:

+
$ bssh --osh selfAddPersonalAccess --host 127.0.0.5 --force
+╭──ac777d06bec9───────────────────────────────────────────the-bastion-3.11.00───
+│ ▶ adding personal access to a server on your account
+├───────────────────────────────────────────────────────────────────────────────
+│ Add a personal server access on your account
+│
+│ Usage: --osh selfAddPersonalAccess --host HOST [OPTIONS]
+│
+│   --host IP|HOST|IP/MASK   Server to add access to
+│   --user USER              Remote login to use, if you want to allow any login, use --user-any
+│   --user-any               Allow access with any remote login
+│   --port PORT              Remote SSH port to use, if you want to allow any port, use --port-any
+│   --port-any               Allow access to all remote ports
+│   --scpup                  Allow SCP upload, you--bastion-->server (omit --user in this case)
+│   --scpdown                Allow SCP download, you<--bastion--server (omit --user in this case)
+│   --sftp                   Allow usage of the SFTP subsystem, you<--bastion-->server (omit --user in this case)
+│   --force                  Add the access without checking that the public SSH key is properly installed remotely
+│   --force-key FINGERPRINT  Only use the key with the specified fingerprint to connect to the server (cf selfListEgressKeys)
+│   --force-password HASH    Only use the password with the specified hash to connect to the server (cf selfListPasswords)
+│   --ttl SECONDS|DURATION   Specify a number of seconds (or a duration string, such as "1d7h8m") after which the access will automatically expire
+│   --comment "'ANY TEXT'"   Add a comment alongside this server. Quote it twice as shown if you're under a shell.
+│
+│ ⛔ No user specified, if you want to add this server with any user, use --user-any
+╰────────────────────────────────────────────────────</selfAddPersonalAccess>───
+
+
+
+
+

v3.10.00 - 2023/02/17

+

No specific upgrade instructions.

+
+
+

v3.09.02 - 2022/11/15

+

No specific upgrade instructions.

+
+
+

v3.09.01 - 2022/10/10

+

No specific upgrade instructions.

+
+
+

v3.09.00 - 2022/09/21

+

This version has changes around the satellite system scripts that should be reviewed:

+
    +

  • The osh-encrypt-rsync.pl script now also handles the account's access log and sql logs, +in addition to the ttyrec files. +A number of new options have been added to this script's config file, these options have sane defaults but you +might still want to review those, namely encrypt_and_move_user_logs_delay_days +and encrypt_and_move_user_sqlites_delay_days.

    • +

  • As a result of the previous feature, the compress-old-logs.sh script has been retired.

    • +

  • A new script, osh-cleanup-guest-key-access.pl, has been added. It is enabled by default, though it can +be disabled if you have a good reason to do so. Please refer to its documentation for more +information.

    • +

  • All scripts that are automatically run by cron and reside under the bin/cron subfolder now have their own +configuration file in /etc/bastion, even for simple scripts that only have two configuration knobs: their +logging facility and whether they should be enabled or not. It is now recommended to use these configuration knobs +to disable the scripts you don't want to see running, instead of removing their corresponding file in the +/etc/cron.d folder, as any future update of the bastion would install them back.

    • +

  • The logging format has been standardized across these scripts, to ensure the newly included NRPE probes can detect +errors in the scripts more easily. By default the logs are going through syslog, using the local6 facility, +which ends up in the /var/log/bastion/bastion-scripts.log folder if you're using our stock syslog-ng +configuration. The NRPE probes are available in the contrib/nrpe directory.

    • +
+

Additionally, NRPE probes have been added, and should be used to monitor your bastion instances / clusters. +More information is available in the NRPE probes readme file.

+

Last but not least, CentOS 8 support has been dropped (whereas RockyLinux 8 will remain supported), +and Ubuntu 22.04 LTS support has been added.

+
+
+

v3.08.01 - 2022/01/19

+

The upgrade path from the preceding version is straightforward, however you might want to know that there is +a new satellite script: osh-remove-empty-folders.sh, run by cron and enabled by default, +whose job is to garbage-collect empty folders that may be piling up in busy users' homes, +under their ttyrec folder.

+

You can find more information in the documentation, the script +is enabled by default because it can do no harm.

+
+
+

v3.08.00 - 2022/01/04

+

This version replaces usage of GnuPG 1.x by GnuPG 2.x for the backup/encrypt/rsync satellite scripts, namely:

+
    +

  • bin/cron/osh-backup-acl-keys.sh

    • +

  • bin/cron/osh-encrypt-rsync.pl

    • +
+

These are optionally used to help you backup your system, and encrypt/move out ttyrec files. +If you don't use these scripts and never configured them as seen in the Advanced Installation section, +then you have nothing to do.

+

The script setup-gpg.sh will now create an Ed25519 key by default, instead of a 4K RSA key. +This type of key is usually seen as more secure (elliptic curve cryptography), and faster than RSA keys. +If you have already configured your system, then the above scripts will continue using the previously generated +RSA key, unless you generate a new key and reference it in the scripts configuration files.

+

If you want to generate new Ed25519 keys instead of using your preexisting RSA keys, you may proceed +to the Ed25519 section below.

+

Otherwise, on the first run, GnuPG 2.x should transparently import the 1.x keyring. +To verify that it worked correctly, you may want to try:

+
/opt/bastion/bin/cron/osh-encrypt-rsync.pl --config-test
+
+
+

If you see Config test passed, and you're okay using your preexisting 4K RSA key, then you may stop here.

+

If the test fails, and you know that before upgrading, this script worked correctly, then you might need to +manually import the GnuPG 1.x public keys:

+
gpg1 --armor --export | gpg --import
+
+
+

Then, try again:

+
/opt/bastion/bin/cron/osh-encrypt-rsync.pl --config-test
+
+
+

If you don't see any errors here, you're done.

+

If you still see errors, then you might need to manually import the private key:

+
gpg1 --armor --export-secret-keys | gpg --import
+
+
+

You may get asked for a password for the bastion secret key, which should be found in +/etc/bastion/osh-encrypt-rsync.conf.d/50-gpg-bastion-key.conf if you previously used the script to generate it.

+

A last config test should now work:

+
/opt/bastion/bin/cron/osh-encrypt-rsync.pl --config-test
+
+
+

If you prefer to generate Ed25519 keys instead, then you can proceed to the next section.

+
+

Ed25519

+

If you want to replace your RSA key by an Ed25519 one (which is optional), then you don't need to import the +GnuPG 1.x keys as outlined above but you may run instead:

+
/opt/bastion/bin/admin/setup-gpg.sh generate --overwrite
+
+
+

Once the key has been generated, you may also want to generate a new admin key, by following this +section of the Advanced Installation documentation. +Note that you'll need to use the --overwrite parameter when importing:

+
/opt/bastion/bin/admin/setup-gpg.sh import --overwrite
+
+
+

Once done, a config test should work:

+
/opt/bastion/bin/cron/osh-encrypt-rsync.pl --config-test
+
+
+
+
+
+

v3.07.00 - 2021/12/13

+

No specific upgrade instructions.

+
+
+

v3.06.00 - 2021/10/15

+

The sshd_config templates have been modified to reflect the changes needed to use +the new --pubkey-auth-optional parameter of accountModify +(#237). +If you want to use it, don't forget to review your sshd_config and modify it accordingly: +the templates can be found in etc/ssh/.

+

Note that misconfiguring sshd and pam together could at worst entirely disable sshd authentication. +If you have a custom configuration, different from the templates we provide, please double-check +that such corner case is not possible by design. +A good way to ensure this is to review the pam configuration and ensure that there is no execution +flow that pushes a pam_success value to the pam stack without requiring any form of authentication.

+
+
+

v3.05.01 - 2021/09/22

+

In the configuration of the osh-backup-acl-keys script, a signing key can now be specified so that the backups +are signed by the bastion key in addition to being encrypted to the admin(s) key(s). +By default, the behaviour is the same as before: encrypt but don't sign.

+
+
+

v3.05.00 - 2021/09/14

+

The maximum length of accounts is now 28 characters up from 18 characters previously. +If you have setup a HA cluster with several bastion instances synchronized together, note that accounts longer +than 18 characters will not be deemed as valid on not-yet upgraded instances of a cluster.

+
+
+

v3.04.00 - 2021/07/02

+

The upgrade path from the preceding version is straightforward, however there are a few changes +that you might want to be aware of before hitting the upgrade button:

+
    +

  • Some EOL OSes have been dropped: Debian 8, Ubuntu 14.04, OpenSUSE 15.0 and 15.1. +This means that while the software might still work, theses OSes are no longer part of the tests +and might break in any future upgrade.

    • +

  • The default logging level of the HTTPS Proxy has been decreased. If you want to keep full requests +and responses logging, check the log_request_response and log_request_response_max_size configuration options.

    • +
+
+
+

v3.03.01 - 2021/03/25

+

No specific upgrade instructions.

+
+
+

v3.03.00 - 2021/02/22

+

No specific upgrade instructions.

+
+
+

v3.02.00 - 2021/02/01

+

The upgrade path from the preceding version is straightforward, however there are a few changes +that you might want to be aware of before hitting the upgrade button:

+
+

The main configuration file now supports proper booleans

+

For a lot of configuration options, previously you would specify "1" to enable a feature, and "0" to disable it. +This has been changed to use proper true and false json values in /etc/bastion/bastion.conf. +Of course, backward compatibility with "0" and "1" will always be kept, so no breakage is to be expected +for this version or future ones even if you keep your configuration untouched.

+
+
+

Logs have been enhanced

+

All connections and plugin executions emit two logs, an open and a close log. +We now add all the details of the connection to the close logs, those that were previously only available +in the corresponding open log. This way, it is no longer required to correlate both logs with their uniqid +to have all the data: the close log should suffice. +The open log is still there if for some reason the close log can't be emitted (kill -9, system crash, etc.), +or if the open and the close log are several hours, days or months appart.

+

An additional field duration has been added to the close logs, +this represents the number of seconds (with millisecond precision) the connection lasted.

+

Two new fields globalsql and accountsql have been added to the open-type logs. +These will contain either ok if we successfully logged to the corresponding log database, +no if it is disabled, or error $aDetailedMessage if we got an error trying to insert the row. +The close-type log also has the new accountsql_close field, but misses the globalsql_close field as +we never update the global database on this event. +On the close log, we can also have the value missing, indicating that we couldn't update the access log row +in the database, as the corresponding open log couldn't insert it.

+

The ttyrecsize log field for the close-type logs has been removed, as it was never completely implemented, +and contains bogus data if ttyrec log rotation occurs. It has also been removed from the sqlite log databases.

+

The open and close events are now pushed to our own log files, in addition to syslog, if logging to those files +is enabled (see enableGlobalAccessLog and enableAccountAccessLog), +previously the close events were only pushed to syslog.

+

The /home/osh.log file is no longer used for enableGlobalAccessLog, the global log +is instead written to /home/logkeeper/global-log-YYYYMM.log.

+

The global sql file, enabled with enableGlobalSqlLog, is now split by year-month instead of by year, +to /home/logkeeper/global-log-YYYYMM.sqlite.

+
+
+
+

v3.01.03 - 2020/12/15

+

No specific upgrade instructions.

+
+
+

v3.01.02 - 2020/12/08

+

No specific upgrade instructions.

+
+
+

v3.01.01 - 2020/12/04

+

No specific upgrade instructions.

+
+
+

v3.01.00 - 2020/11/20

+

A new bastion.conf option was introduced: interactiveModeByDefault. If not present in your config file, +its value defaults to 1 (true), which changes the behavior of The Bastion when a user connects +without specifying any command. +When this happens, it'll now display the help then drop the user into interactive mode (if this mode is enabled), +instead of displaying the help and aborting with an error message. +Set it to 0 (false) if you want to keep the previous behavior.

+

An SELinux module has been added in this version, to ensure TOTP MFA works correctly under systems where SELinux +is on enforcing mode. This module will be installed automatically whenever SELinux is detected on the system. +If you don't want to use this module, specify --no-install-selinux-module on your /opt/bastion/bin/admin/install +upgrade call (please refer to the generic upgrade instructions for more details).

+
+
+

v3.00.02 - 2020/11/16

+

No specific upgrade instructions.

+
+
+

v3.00.01 - 2020/11/06

+

If you previously installed ttyrec using the now deprecated build-and-install-ttyrec.sh script, +you might want to know that since this version, the script has been replaced by install-ttyrec.sh, +which no longer builds in-place, but prefers downloading and installing prebuild rpm or deb packages.

+

If you previously built and installed ttyrec manually, and want to use the new packages instead, +you might want to manually uninstall your previously built ttyrec program (remove the binaries that were installed +in /usr/local/bin), and call install-ttyrec.sh -a to download and install the proper package instead.

+

This is not mandatory and doesn't change anything from the software point of view.

+
+
+

v3.00.00 - 2020/10/30

+

Initial public version, no specific upgrade instructions.

+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/objects.inv b/objects.inv new file mode 100644 index 0000000..253a5a0 Binary files /dev/null and b/objects.inv differ diff --git a/plugins/admin/adminMaintenance.html b/plugins/admin/adminMaintenance.html new file mode 100644 index 0000000..8cce43b --- /dev/null +++ b/plugins/admin/adminMaintenance.html @@ -0,0 +1,178 @@ + + + + + + + adminMaintenance — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

adminMaintenance

+
+

Manage the bastion maintenance mode

+
+

usage

+

--osh adminMaintenance <--lock [--message "'reason for maintenance'"]|--unlock>

+
+
+
+--lock
+

Set maintenance mode: new logins will be disallowed

+
+ +
+
+--unlock
+

Unset maintenance mode: new logins are allowed and the bastion functions normally

+
+ +
+
+--message MESSAGE
+

Optionally set a maintenance reason, if you're in a shell, quote it twice.

+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/admin/adminSudo.html b/plugins/admin/adminSudo.html new file mode 100644 index 0000000..67589f2 --- /dev/null +++ b/plugins/admin/adminSudo.html @@ -0,0 +1,178 @@ + + + + + + + adminSudo — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

adminSudo

+
+

Impersonate another user

+
+

usage

+

--osh adminSudo -- --sudo-as ACCOUNT <--sudo-cmd PLUGIN -- [PLUGIN specific options...]>

+
+
+
+--sudo-as ACCOUNT
+

Specify which bastion account we want to impersonate

+
+ +
+
+--sudo-cmd PLUGIN
+

--osh command we want to launch as the user (see --osh help)

+
+ +

Example:

+
--osh adminSudo -- --sudo-as user12 --sudo-cmd info -- --name somebodyelse
+
+
+

Don't forget the double-double-dash as seen in the example above: one after the plugin name, +and another one to separate adminSudo options from the options of the plugin to be called.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/admin/index.html b/plugins/admin/index.html new file mode 100644 index 0000000..36f385b --- /dev/null +++ b/plugins/admin/index.html @@ -0,0 +1,161 @@ + + + + + + + admin plugins — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+ +
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/group-aclkeeper/groupAddServer.html b/plugins/group-aclkeeper/groupAddServer.html new file mode 100644 index 0000000..fcbd073 --- /dev/null +++ b/plugins/group-aclkeeper/groupAddServer.html @@ -0,0 +1,241 @@ + + + + + + + groupAddServer — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

groupAddServer

+
+

Add an IP or IP block to a group's servers list

+
+

usage

+

--osh groupAddServer --group GROUP --host HOST --user USER|* --port PORT|* [OPTIONS]

+
+
+
+--group GROUP
+

Specify which group this machine should be added to

+
+ +
+
+--host HOST|IP|NET/CIDR
+
+

Host(s) to add access to, either a HOST which will be resolved to an IP immediately,

+
+

or an IP, or a whole network using the NET/CIDR notation

+
+
+
+
--user USER|PATTERN|* Specify which remote user should be allowed to connect as.

Globbing characters '*' and '?' are supported, so you can specify a pattern +that will be matched against the actual remote user name. +To allow any user, use '--user ' (you might need to escape '' from your shell)

+
+
--port PORT|* Remote port allowed to connect to

To allow any port, use '--port ' (you might need to escape '' from your shell)

+
+
+
+ +
+
+--protocol PROTO
+

Specify that a special protocol should be allowed for this HOST:PORT tuple, note that you

+
+

must not specify --user in that case. However, for this protocol to be usable under a given +remote user, access to the USER@HOST:PORT tuple must also be allowed. +PROTO must be one of: +scpup allow SCP upload, you--bastion-->server +scpdown allow SCP download, you<--bastion--server +sftp allow usage of the SFTP subsystem, through the bastion +rsync allow usage of rsync, through the bastion

+
+
+ +
+
+--force
+

Don't try the ssh connection, just add the host to the group blindly

+
+ +
+
+--force-key FINGERPRINT
+

Only use the key with the specified fingerprint to connect to the server (cf groupInfo)

+
+ +
+
+--force-password HASH
+

Only use the password with the specified hash to connect to the server (cf groupListPasswords)

+
+ +
+
+--ttl SECONDS|DURATION
+

Specify a number of seconds (or a duration string, such as "1d7h8m") after which the access will automatically expire

+
+ +
+
+--comment "'ANY TEXT'"
+

Add a comment alongside this server. Quote it twice as shown if you're under a shell.

+
+ +

Examples:

+
--osh groupAddServer --group grp1 --host 203.0.113.0/24 --user '*' --port '*' --force --ttl 1d12h --comment '"a whole network"'
+--osh groupAddServer --group grp2 --host srv1.example.org --user data --port 22
+--osh groupAddServer --group grp2 --host srv1.example.org --user file --port 22
+
+
+

Example to allow using sftp to srv1.example.org using remote user 'data' or 'file', in addition to the above commands:

+
--osh groupAddServer --group grp2 --host srv1.example.org --port 22 --protocol sftp
+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/group-aclkeeper/groupDelServer.html b/plugins/group-aclkeeper/groupDelServer.html new file mode 100644 index 0000000..bbc4049 --- /dev/null +++ b/plugins/group-aclkeeper/groupDelServer.html @@ -0,0 +1,206 @@ + + + + + + + groupDelServer — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

groupDelServer

+
+

Remove an IP or IP block from a group's server list

+
+

usage

+

--osh groupDelServer --group GROUP --host HOST --user USER --port PORT [OPTIONS]

+
+
+
+--group GROUP
+

Specify which group this machine should be removed from

+
+ +
+
+--host HOST|IP|NET/CIDR
+
+

Host(s) to remove access from, either a HOST which will be resolved to an IP immediately,

+
+

or an IP, or a whole network using the NET/CIDR notation

+
+
+
+
--user USER|PATTERN|* Specify which remote user was allowed to connect as.

Globbing characters '*' and '?' are supported, so you can specify a pattern +that will be matched against the actual remote user name. +If any user was allowed, use '--user ' (you might need to escape '' from your shell)

+
+
--port PORT|* Remote port that was allowed to connect to

If any port was allowed, use '--port ' (you might need to escape '' from your shell)

+
+
+
+ +
+
+--protocol PROTO
+

Specify that a special protocol allowance should be removed from this HOST:PORT tuple, note that you

+
+

must not specify --user in that case. +PROTO must be one of: +scpup allow SCP upload, you--bastion-->server +scpdown allow SCP download, you<--bastion--server +sftp allow usage of the SFTP subsystem, through the bastion +rsync allow usage of rsync, through the bastion

+
+
+ +

This command adds, to an existing bastion account, access to a given server, using the +egress keys of the group. The list of eligible servers for a given group is given by groupListServers

+

If you want to add member access to an account to all the present and future servers +of the group, using the group key, please use groupAddMember instead.

+

If you want to add access to an account to a group server but using their personal bastion +key instead of the group key, please use accountAddPersonalAccess instead.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/group-aclkeeper/groupSetServers.html b/plugins/group-aclkeeper/groupSetServers.html new file mode 100644 index 0000000..cc5ada7 --- /dev/null +++ b/plugins/group-aclkeeper/groupSetServers.html @@ -0,0 +1,191 @@ + + + + + + + groupSetServers — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

groupSetServers

+
+

Replace a group's current ACL by a new list

+
+

usage

+

--osh groupSetServers --group GROUP [OPTIONS]

+
+
+
+--group GROUP
+

Specify which group to modify the ACL of

+
+ +
+
+--dry-run
+

Don't actually modify the ACL, just report whether the input contains errors

+
+ +
+
+--skip-errors
+

Don't abort on STDIN parsing errors, just skip the non-parseable lines

+
+ +

The list of the assets to constitute the new ACL should then be given on STDIN, +respecting the following format: [USER@]HOST[:PORT][ COMMENT], with USER and PORT being optional, +and HOST being either a hostname, an IP, or an IP block in CIDR notation. The COMMENT is also optional, +and may contain spaces.

+

Example of valid lines to be fed through STDIN:

+
server12.example.org
+logs@server
+192.0.2.21
+host1.example.net:2222 host1 on secondary sshd with alternate port
+root@192.0.2.0/24 production database cluster
+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/group-aclkeeper/index.html b/plugins/group-aclkeeper/index.html new file mode 100644 index 0000000..ea68028 --- /dev/null +++ b/plugins/group-aclkeeper/index.html @@ -0,0 +1,166 @@ + + + + + + + group-aclkeeper plugins — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+ +
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/group-gatekeeper/groupAddGuestAccess.html b/plugins/group-gatekeeper/groupAddGuestAccess.html new file mode 100644 index 0000000..c70f7fb --- /dev/null +++ b/plugins/group-gatekeeper/groupAddGuestAccess.html @@ -0,0 +1,235 @@ + + + + + + + groupAddGuestAccess — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

groupAddGuestAccess

+
+

Add a specific group server access to an account

+
+

usage

+

--osh groupAddGuestAccess --group GROUP --account ACCOUNT [OPTIONS]

+
+
+
+--account ACCOUNT
+

Name of the other bastion account to add access to, they'll be given access to the GROUP key

+
+ +
+
+--group GROUP
+

Group to add the guest access to, note that this group should already have access

+
+

to the USER/HOST/PORT tuple you'll specify with the options below.

+
+
+ +
+
+--host HOST|IP|NET/CIDR
+
+

Host(s) to add access to, either a HOST which will be resolved to an IP immediately,

+
+

or an IP, or a whole network using the NET/CIDR notation

+
+
+
+
--user USER|PATTERN|* Specify which remote user should be allowed to connect as.

Globbing characters '*' and '?' are supported, so you can specify a pattern +that will be matched against the actual remote user name. +To allow any user, use '--user ' (you might need to escape '' from your shell)

+
+
--port PORT|* Remote port allowed to connect to

To allow any port, use '--port ' (you might need to escape '' from your shell)

+
+
+
+ +
+
+--protocol PROTO
+

Specify that a special protocol should be allowed for this HOST:PORT tuple, note that you

+
+

must not specify --user in that case. However, for this protocol to be usable under a given +remote user, access to the USER@HOST:PORT tuple must also be allowed. +PROTO must be one of: +scpup allow SCP upload, you--bastion-->server +scpdown allow SCP download, you<--bastion--server +sftp allow usage of the SFTP subsystem, through the bastion +rsync allow usage of rsync, through the bastion

+
+
+ +
+
+--ttl SECONDS|DURATION
+

Specify a number of seconds after which the access will automatically expire

+
+ +
+
+--comment '"ANY TEXT"'
+

Add a comment alongside this access. Quote it twice as shown if you're under a shell.

+
+

If omitted, we'll use the closest preexisting group access' comment as seen in groupListServers

+
+
+ +

This command adds, to an existing bastion account, access to the egress keys of a group, +but only to accessing one or several given servers, instead of all the servers of this group.

+

If you want to add complete access to an account to all the present and future servers +of the group, using the group key, please use groupAddMember instead.

+

If you want to add access to an account to a group server but using his personal bastion +key instead of the group key, please use accountAddPersonalAccess instead (his public key +must be on the remote server).

+

This command is the opposite of groupDelGuestAccess.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/group-gatekeeper/groupAddMember.html b/plugins/group-gatekeeper/groupAddMember.html new file mode 100644 index 0000000..c152325 --- /dev/null +++ b/plugins/group-gatekeeper/groupAddMember.html @@ -0,0 +1,179 @@ + + + + + + + groupAddMember — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

groupAddMember

+
+

Add an account to the member list

+
+

usage

+

--osh groupAddMember --group GROUP --account ACCOUNT

+
+
+
+--group GROUP
+

which group to set ACCOUNT as a member of

+
+ +
+
+--account ACCOUNT
+

which account to set as a member of GROUP

+
+ +

The specified account will be able to access all present and future servers +pertaining to this group. +If you need to give a specific and/or temporary access instead, +see groupAddGuestAccess

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/group-gatekeeper/groupDelGuestAccess.html b/plugins/group-gatekeeper/groupDelGuestAccess.html new file mode 100644 index 0000000..333fa9f --- /dev/null +++ b/plugins/group-gatekeeper/groupDelGuestAccess.html @@ -0,0 +1,216 @@ + + + + + + + groupDelGuestAccess — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

groupDelGuestAccess

+
+

Remove a specific group server access from an account

+
+

usage

+

--osh groupDelGuestAccess --group GROUP --account ACCOUNT [OPTIONS]

+
+
+
+--account ACCOUNT
+

Bastion account remove the guest access from

+
+ +
+
+--group GROUP
+

Specify which group to remove the guest access to ACCOUNT from

+
+ +
+
+--host HOST|IP|NET/CIDR
+
+

Host(s) to remove access from, either a HOST which will be resolved to an IP immediately,

+
+

or an IP, or a whole network using the NET/CIDR notation

+
+
+
+
--user USER|PATTERN|* Specify which remote user was allowed to connect as.

Globbing characters '*' and '?' are supported, so you can specify a pattern +that will be matched against the actual remote user name. +If any user was allowed, use '--user ' (you might need to escape '' from your shell)

+
+
--port PORT|* Remote port that was allowed to connect to

If any user was allowed, use '--port ' (you might need to escape '' from your shell)

+
+
+
+ +
+
+--protocol PROTO
+

Specify that a special protocol was allowed for this HOST:PORT tuple, note that you

+
+

must not specify --user in that case. However, for this protocol to be usable under a given +remote user, access to the USER@HOST:PORT tuple must also be allowed. +PROTO must be one of: +scpup allow SCP upload, you--bastion-->server +scpdown allow SCP download, you<--bastion--server +sftp allow usage of the SFTP subsystem, through the bastion +rsync allow usage of rsync, through the bastion

+
+
+ +

This command removes, from an existing bastion account, access to a given server, using the +egress keys of the group. The list of such servers is given by groupListGuestAccesses

+

If you want to remove member access from an account to all the present and future servers +of the group, using the group key, please use groupDelMember instead.

+

If you want to remove access from an account from a group server but using their personal bastion +key instead of the group key, please use accountDelPersonalAccess instead.

+

This command is the opposite of groupAddGuestAccess.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/group-gatekeeper/groupDelMember.html b/plugins/group-gatekeeper/groupDelMember.html new file mode 100644 index 0000000..dfdd16d --- /dev/null +++ b/plugins/group-gatekeeper/groupDelMember.html @@ -0,0 +1,179 @@ + + + + + + + groupDelMember — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

groupDelMember

+
+

Remove an account from the members list

+
+

usage

+

--osh groupDelMember --group GROUP --account ACCOUNT

+
+
+
+--group GROUP
+

which group to remove ACCOUNT as a member of

+
+ +
+
+--account ACCOUNT
+

which account to remove as a member of GROUP

+
+ +

The specified account will no longer be able to access all present and future servers +pertaining to this group. +Note that if this account also had specific guest accesses to this group, they may +still apply, see groupListGuestAccesses

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/group-gatekeeper/groupListGuestAccesses.html b/plugins/group-gatekeeper/groupListGuestAccesses.html new file mode 100644 index 0000000..90427d1 --- /dev/null +++ b/plugins/group-gatekeeper/groupListGuestAccesses.html @@ -0,0 +1,203 @@ + + + + + + + groupListGuestAccesses — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

groupListGuestAccesses

+
+

List the guest accesses to servers of a group specifically granted to an account

+
+

usage

+

--osh groupListGuestAccesses --group GROUP --account ACCOUNT

+
+
+
+--group GROUP
+

Look for accesses to servers of this GROUP

+
+ +
+
+--account ACCOUNT
+

Which account to check

+
+ +
+
+--reverse-dns
+

Attempt to resolve the reverse hostnames (SLOW!)

+
+ +
+
+--include PATTERN
+

Only include servers matching the given PATTERN (see below)

+
+

This option can be used multiple times to refine results

+
+
+ +
+
+--exclude PATTERN
+

Omit servers matching the given PATTERN (see below)

+
+

This option can be used multiple times. +Note that --exclude takes precedence over --include

+
+
+ +

Note: PATTERN supports the * and ? wildcards. +If PATTERN is a simple string without wildcards, then names containing this string will be considered. +The matching is done on the text output of the command.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/group-gatekeeper/index.html b/plugins/group-gatekeeper/index.html new file mode 100644 index 0000000..c3d23aa --- /dev/null +++ b/plugins/group-gatekeeper/index.html @@ -0,0 +1,176 @@ + + + + + + + group-gatekeeper plugins — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+ +
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/group-owner/groupAddAclkeeper.html b/plugins/group-owner/groupAddAclkeeper.html new file mode 100644 index 0000000..dcd37e8 --- /dev/null +++ b/plugins/group-owner/groupAddAclkeeper.html @@ -0,0 +1,183 @@ + + + + + + + groupAddAclkeeper — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

groupAddAclkeeper

+
+

Add the group aclkeeper role to an account

+
+

usage

+

--osh groupAddAclkeeper --group GROUP --account ACCOUNT

+
+
+
+--group GROUP
+

which group to set ACCOUNT as an aclkeeper of

+
+ +
+
+--account ACCOUNT
+

which account to set as an aclkeeper of GROUP

+
+ +

The specified account will be able to manage the server list of this group

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/group-owner/groupAddGatekeeper.html b/plugins/group-owner/groupAddGatekeeper.html new file mode 100644 index 0000000..db55337 --- /dev/null +++ b/plugins/group-owner/groupAddGatekeeper.html @@ -0,0 +1,184 @@ + + + + + + + groupAddGatekeeper — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

groupAddGatekeeper

+
+

Add the group gatekeeper role to an account

+
+

usage

+

--osh groupAddGatekeeper --group GROUP --account ACCOUNT

+
+
+
+--group GROUP
+

which group to set ACCOUNT as a gatekeeper of

+
+ +
+
+--account ACCOUNT
+

which account to set as a gatekeeper of GROUP

+
+ +

The specified account will be able to manage the members list of this group, +along with the guests list

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/group-owner/groupAddOwner.html b/plugins/group-owner/groupAddOwner.html new file mode 100644 index 0000000..32f9885 --- /dev/null +++ b/plugins/group-owner/groupAddOwner.html @@ -0,0 +1,186 @@ + + + + + + + groupAddOwner — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

groupAddOwner

+
+

Add the group owner role to an account

+
+

usage

+

--osh groupAddOwner --group GROUP --account ACCOUNT

+
+
+
+--group GROUP
+

which group to set ACCOUNT as an owner of

+
+ +
+
+--account ACCOUNT
+

which account to set as an owner of GROUP

+
+ +

The specified account will be able to manage the owner, gatekeeper +and aclkeeper list of this group. In other words, this account will +have all possible rights to manage the group and delegate some or all +of the rights to other accounts

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/group-owner/groupDelAclkeeper.html b/plugins/group-owner/groupDelAclkeeper.html new file mode 100644 index 0000000..a2ed8a3 --- /dev/null +++ b/plugins/group-owner/groupDelAclkeeper.html @@ -0,0 +1,183 @@ + + + + + + + groupDelAclkeeper — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

groupDelAclkeeper

+
+

Remove the group aclkeeper role from an account

+
+

usage

+

--osh groupDelAclkeeper --group GROUP --account ACCOUNT

+
+
+
+--group GROUP
+

which group to remove ACCOUNT as an aclkeeper of

+
+ +
+
+--account ACCOUNT
+

which account to remove as an aclkeeper of GROUP

+
+ +

The specified account will no longer be able to manage the server list of this group

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/group-owner/groupDelEgressKey.html b/plugins/group-owner/groupDelEgressKey.html new file mode 100644 index 0000000..0b4c608 --- /dev/null +++ b/plugins/group-owner/groupDelEgressKey.html @@ -0,0 +1,182 @@ + + + + + + + groupDelEgressKey — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

groupDelEgressKey

+
+

Remove a bastion group egress key

+
+

usage

+

--osh groupDelEgressKey <--group GROUP> <--id ID>

+
+
+
+--group GROUP
+

Name of the group to delete the egress key from

+
+ +
+
+--id ID
+

Specify the key ID to delete, you can get it with groupInfo

+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/group-owner/groupDelGatekeeper.html b/plugins/group-owner/groupDelGatekeeper.html new file mode 100644 index 0000000..e0e6a19 --- /dev/null +++ b/plugins/group-owner/groupDelGatekeeper.html @@ -0,0 +1,184 @@ + + + + + + + groupDelGatekeeper — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

groupDelGatekeeper

+
+

Remove the group gatekeeper role from an account

+
+

usage

+

--osh groupDelGatekeeper --group GROUP --account ACCOUNT

+
+
+
+--group GROUP
+

which group to remove ACCOUNT as a gatekeeper of

+
+ +
+
+--account ACCOUNT
+

which account to remove as a gatekeeper of GROUP

+
+ +

The specified account will no longer be able to manager the members nor +the guest list of this group

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/group-owner/groupDelOwner.html b/plugins/group-owner/groupDelOwner.html new file mode 100644 index 0000000..ffb0821 --- /dev/null +++ b/plugins/group-owner/groupDelOwner.html @@ -0,0 +1,184 @@ + + + + + + + groupDelOwner — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

groupDelOwner

+
+

Remove the group owner role from an account

+
+

usage

+

--osh groupDelOwner --group GROUP --account ACCOUNT

+
+
+
+--group GROUP
+

which group to set ACCOUNT as an owner of

+
+ +
+
+--account ACCOUNT
+

which account to set as an owner of GROUP

+
+ +

The specified account will no longer be able to manage the owner, +gatekeeper and aclkeeper lists of this group

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/group-owner/groupDestroy.html b/plugins/group-owner/groupDestroy.html new file mode 100644 index 0000000..d5b8e8e --- /dev/null +++ b/plugins/group-owner/groupDestroy.html @@ -0,0 +1,184 @@ + + + + + + + groupDestroy — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

groupDestroy

+
+

Delete a group

+
+

usage

+

--osh groupDestroy --group GROUP

+
+
+
+--group GROUP
+

Group name to delete

+
+ +
+
+--no-confirm
+

Skip group name confirmation, but blame yourself if you deleted the wrong group!

+
+ +

This command is able to delete any group you're an owner of. +Granted users to the sibling restricted command groupDelete can delete any group.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/group-owner/groupGenerateEgressKey.html b/plugins/group-owner/groupGenerateEgressKey.html new file mode 100644 index 0000000..d8d87b4 --- /dev/null +++ b/plugins/group-owner/groupGenerateEgressKey.html @@ -0,0 +1,207 @@ + + + + + + + groupGenerateEgressKey — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

groupGenerateEgressKey

+
+

Create a new public + private key pair for a group

+
+

usage

+

--osh groupGenerateEgressKey --group GROUP --algo ALGO --size SIZE [--encrypted]

+
+
+
+--group GROUP
+

Group name to generate a new egress key for.

+
+ +
+
+--algo ALGO
+

Specifies the algo of the key, either rsa, ecdsa or ed25519.

+
+ +
+
+--size SIZE
+

Specifies the size of the key to be generated.

+
+

For RSA, choose between 2048 and 8192 (4096 is good). +For ECDSA, choose either 256, 384 or 521. +For Ed25519, size is always 256.

+
+
+ +
+
+--encrypted
+

If specified, a passphrase will be prompted for the new key

+
+ +

A quick overview of the different algorithms:

+
Ed25519      : robustness[###] speed[###]
+ECDSA        : robustness[##.] speed[###]
+RSA          : robustness[#..] speed[#..]
+
+
+

This table is meant as a quick cheat-sheet, you're warmly advised to do +your own research, as other constraints may apply to your environment.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/group-owner/groupGeneratePassword.html b/plugins/group-owner/groupGeneratePassword.html new file mode 100644 index 0000000..a5eb857 --- /dev/null +++ b/plugins/group-owner/groupGeneratePassword.html @@ -0,0 +1,197 @@ + + + + + + + groupGeneratePassword — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

groupGeneratePassword

+
+

Generate a new egress password for the group

+
+

usage

+

--osh groupGeneratePassword --group GROUP [--size SIZE] --do-it

+
+
+
+--group GROUP
+

Specify which group you want to generate a password for

+
+ +
+
+--size  SIZE
+

Specify the number of characters of the password to generate

+
+ +
+
+--do-it
+

Required for the password to actually be generated, BEWARE: please read the note below

+
+ +

Generate a new egress password to be used for ssh or telnet

+

NOTE: this is only needed for devices that don't support key-based SSH, +in most cases you should ignore this command completely, unless you +know that devices you need to access only support telnet or password-based SSH.

+

BEWARE: once a new password is generated this way, it'll be set as the new +egress password to use right away for the group, for any access that requires it. +A fallback mechanism exists that will auto-try the previous password if this one +doesn't work, but please ensure that this new password is deployed on the remote +devices as soon as possible.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/group-owner/groupModify.html b/plugins/group-owner/groupModify.html new file mode 100644 index 0000000..7da250d --- /dev/null +++ b/plugins/group-owner/groupModify.html @@ -0,0 +1,204 @@ + + + + + + + groupModify — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

groupModify

+
+

Modify the configuration of a group

+
+

usage

+

--osh groupModify --group GROUP [--mfa-required password|totp|any|none] [--guest-ttl-limit DURATION]

+
+
+
+--group             GROUP
+

Name of the group to modify

+
+ +
+
+--mfa-required      password|totp|any|none
+
+

Enforce UNIX password requirement, or TOTP requirement, or any MFA requirement, when connecting to a server of the group

+
+
+
--idle-lock-timeout DURATION|0|-1 Overrides the global setting (idleLockTimeout), to the specified duration. If set to 0, disables idleLockTimeout for

this group. If set to -1, remove this group override and use the global setting instead.

+
+
--idle-kill-timeout DURATION|0|-1 Overrides the global setting (idleKillTimeout), to the specified duration. If set to 0, disables idleKillTimeout for

this group. If set to -1, remove this group override and use the global setting instead.

+
+
+
+ +
+
+--guest-ttl-limit   DURATION
+

This group will enforce TTL setting, on guest access creation, to be set, and not to a higher value than DURATION,

+
+

set to zero to allow guest accesses creation without any TTL set (default)

+
+
+ +

Note that --idle-lock-timeout and --idle-kill-timeout will NOT be applied for catch-all groups (having 0.0.0.0/0 in their server list).

+

If a server is in exactly one group an account is a member of, then its values of --idle-lock-timeout and --idle-kill-timeout, if set, +will prevail over the global setting. The global setting can be seen with --osh info.

+

Otherwise, the most restrictive setting (i.e. the one with the lower strictly positive duration) between +all the considered groups and the global setting, will be used.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/group-owner/groupTransmitOwnership.html b/plugins/group-owner/groupTransmitOwnership.html new file mode 100644 index 0000000..e991dab --- /dev/null +++ b/plugins/group-owner/groupTransmitOwnership.html @@ -0,0 +1,184 @@ + + + + + + + groupTransmitOwnership — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

groupTransmitOwnership

+
+

Transmit your group ownership to somebody else

+
+

usage

+

--osh groupTransmitOwnership --group GROUP --account ACCOUNT

+
+
+
+--group GROUP
+

which group to set ACCOUNT as an owner of

+
+ +
+
+--account ACCOUNT
+

which account to set as an owner of GROUP

+
+ +

Note that this command has the same net effect than using groupAddOwner +to add ACCOUNT as an owner, then removing yourself with groupDelOwner

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/group-owner/index.html b/plugins/group-owner/index.html new file mode 100644 index 0000000..7d38af7 --- /dev/null +++ b/plugins/group-owner/index.html @@ -0,0 +1,211 @@ + + + + + + + group-owner plugins — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

group-owner plugins

+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/alive.html b/plugins/open/alive.html new file mode 100644 index 0000000..2fcd2dd --- /dev/null +++ b/plugins/open/alive.html @@ -0,0 +1,199 @@ + + + + + + + alive — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

alive

+
+

Ping a host and exit as soon as it answers

+

This command can be used to monitor a host that is expected to go back online soon. +Note that if you want to ssh to it afterwards, you can simply use the --wait main option.

+
+

usage

+

--osh alive [--host] HOSTNAME

+
+
+
+--host HOSTNAME
+

hostname or IP to ping

+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/batch.html b/plugins/open/batch.html new file mode 100644 index 0000000..029a6e8 --- /dev/null +++ b/plugins/open/batch.html @@ -0,0 +1,211 @@ + + + + + + + batch — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

batch

+
+

Run a batch of osh commands fed through STDIN

+
+

usage

+

--osh batch

+
+

Examples:

+

(replace bssh by your bastion alias)

+
    +

  • run 3 simple commands in a oneliner:

    • +
+
printf "%b\n%b\n%b" info selfListIngressKeys selfListEgressKeys | bssh --osh batch
+
+
+
    +

  • run a lot of commands written out line by line in a file:

    • +
+
bssh --osh batch < cmdlist.txt
+
+
+
    +

  • add 3 users to a group:

    • +
+
for i in user1 user2 user3; do echo "groupAddMember --account $i --group grp4"; done | bssh --osh batch
+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/clush.html b/plugins/open/clush.html new file mode 100644 index 0000000..305bbb4 --- /dev/null +++ b/plugins/open/clush.html @@ -0,0 +1,233 @@ + + + + + + + clush — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

clush

+
+

Launch a remote command on several machines sequentially (clush-like)

+
+

usage

+

--osh clush [OPTIONS] --command '"remote command"'

+
+
+
+--list HOSTLIST
+

Comma-separated list of the hosts (hostname or IP) to run the command on

+
+ +
+
+--user USER
+

Specify which remote user should we use to connect (default: BASTION_ACCOUNT)

+
+ +
+
+--port PORT
+

Specify which port to connect to (default: 22)

+
+ +
+
+--step-by-step
+

Pause before running the command on each host

+
+ +
+
+--no-pause-on-failure
+

Don't pause if the remote command failed (returned exit code != 0)

+
+ +
+
+--no-confirm
+

Skip confirmation of the host list and command

+
+ +
+
+--command '"remote cmd"'
+

Command to be run on the remote hosts. If you're in a shell, quote it twice as shown.

+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/groupInfo.html b/plugins/open/groupInfo.html new file mode 100644 index 0000000..db2a9e1 --- /dev/null +++ b/plugins/open/groupInfo.html @@ -0,0 +1,238 @@ + + + + + + + groupInfo — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

groupInfo

+ +
+

Usage examples

+

Show info about a specific group:

+
--osh groupInfo --group mygroup2
+
+
+

Gather info about all groups, with no extra data except their keys:

+
--osh groupInfo --all --without-everything --with-keys --json
+
+
+

Gather info about all groups, including all extra data (and possibly future options):

+
--osh groupInfo --all --with-everything --json
+
+
+
+
+

Output example

+

The first paragraph of the output lists the different roles along with the people having these roles.

+

You can also see the public egress key of this group, i.e. the key that needs to be added to the remote servers' authorized_keys files, so that members of this group can access these servers.

+

Note that if you want to see the list of servers pertaining to this group, you can use the command groupListServers.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/groupList.html b/plugins/open/groupList.html new file mode 100644 index 0000000..79511a0 --- /dev/null +++ b/plugins/open/groupList.html @@ -0,0 +1,218 @@ + + + + + + + groupList — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

groupList

+
+

List the groups available on this bastion

+
+

usage

+

--osh groupList [--all] [--exclude|--include PATTERN [--exclude|--include PATTERN ..]]

+
+
+
+--all
+

List all groups, even those to which you don't have access

+
+ +
+
+--include PATTERN
+

Only list groups that match the given PATTERN (see below)

+
+

This option can be used multiple times to refine results

+
+
+ +
+
+--exclude PATTERN
+

Omit groups that match the given PATTERN string (see below)

+
+

This option can be used multiple times. +Note that --exclude takes precedence over --include

+
+
+ +

Note: PATTERN supports the * and ? wildcards. +If PATTERN is a simple string without wildcards, then names containing this string will be considered.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/groupListPasswords.html b/plugins/open/groupListPasswords.html new file mode 100644 index 0000000..9c50583 --- /dev/null +++ b/plugins/open/groupListPasswords.html @@ -0,0 +1,198 @@ + + + + + + + groupListPasswords — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

groupListPasswords

+
+

List the hashes and metadata of egress passwords of a group

+
+

usage

+

--osh groupListPasswords --group GROUP

+
+
+
+--group GROUP
+

Show the data for this group

+
+ +

The passwords corresponding to these hashes are only needed for devices that don't support key-based SSH

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/groupListServers.html b/plugins/open/groupListServers.html new file mode 100644 index 0000000..9b30a08 --- /dev/null +++ b/plugins/open/groupListServers.html @@ -0,0 +1,225 @@ + + + + + + + groupListServers — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

groupListServers

+
+

List the servers (IPs and IP blocks) pertaining to a group

+
+

usage

+

--osh groupListServers --group GROUP [--reverse-dns]

+
+
+
+--group GROUP
+

List the servers of this group

+
+ +
+
+--reverse-dns
+

Attempt to resolve the reverse hostnames (SLOW!)

+
+ +
+
+--include PATTERN
+

Only include servers matching the given PATTERN (see below)

+
+

This option can be used multiple times to refine results

+
+
+ +
+
+--exclude PATTERN
+

Omit servers matching the given PATTERN (see below)

+
+

This option can be used multiple times. +Note that --exclude takes precedence over --include

+
+
+ +

Note: PATTERN supports the * and ? wildcards. +If PATTERN is a simple string without wildcards, then names containing this string will be considered. +The matching is done on the text output of the command.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/help.html b/plugins/open/help.html new file mode 100644 index 0000000..d1e2d30 --- /dev/null +++ b/plugins/open/help.html @@ -0,0 +1,206 @@ + + + + + + + help — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

help

+
+

I'm So Meta, Even This Acronym

+
+

usage

+

--osh help

+
+

Displays help about the available plugins callable with --osh.

+

If you need help on a specific plugin, you can use --osh PLUGIN --help, replacing PLUGIN with the actual plugin name.

+

Note that if you want some help about the bastion (and not specifically about the plugins), you should use --help (without --osh).

+
+
+

Colors

+

You'll notice that plugins are highlighted in different colors, these indicate the access level needed to run the plugin. Note that plugins you don't have access to are simply omitted.

+
    +

  • green (open): these plugins can be called by anybody

    • +

  • blue (restricted): these plugins can only be called by users having the specific right to call them. This right is granted per plugin by the accountGrantCommand plugin

    • +

  • orange (group-gatekeeper and group-aclkeeper): these plugins can either be called by group gatekeepers or group aclkeepers. For clarity, the same color has been used for both cases

    • +

  • purple (group-owner): these plugins can only be called by group owners

    • +

  • red (admin): these plugins can only be called by bastion admins

    • +
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/index.html b/plugins/open/index.html new file mode 100644 index 0000000..da11dc9 --- /dev/null +++ b/plugins/open/index.html @@ -0,0 +1,328 @@ + + + + + + + open plugins — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

open plugins

+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/info.html b/plugins/open/info.html new file mode 100644 index 0000000..9f9e6e9 --- /dev/null +++ b/plugins/open/info.html @@ -0,0 +1,268 @@ + + + + + + + info — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

info

+
+

Displays some information about this bastion instance

+
+

usage

+

--osh info

+
+
+
+

Output example

+
~ You are user1
+~
+~ Your alias to connect to this bastion is:
+~ alias bastion='ssh user1@testbastion.example.org -p 22 -t -- '
+~ Your alias to connect to this bastion with MOSH is:
+~ alias bastionm='mosh --ssh="ssh -p 22 -t" user1@testbastion.example.org -- '
+~
+~ Multi-Factor Authentication (MFA) on your account:
+~ - Additional password authentication is not required
+~ - Additional password authentication bypass is disabled
+~ - Additional password authentication is enabled and active
+~ - Additional TOTP authentication is not required
+~ - Additional TOTP authentication bypass is disabled
+~ - Additional TOTP authentication is disabled
+~
+~ I am testbastion-a.example.org, aka bastion
+~ I have 42 registered accounts and 46 groups
+~ I am a MASTER, which means I accept modifications
+~ The networks I'm able to connect you to on the egress side are: all
+~ The networks that are explicitly forbidden on the egress side are: none
+~ My egress connection IP to remote servers is 192.0.2.45/32
+~ ...don't forget to whitelist me in your firewalls!
+~
+~ The following policy applies on this bastion:
+~ - The interactive mode (-i) is ENABLED
+~ - The support of mosh is ENABLED
+~ - Account expiration is DISABLED
+~ - Keyboard input idle time for session locking is DISABLED
+~ - Keyboard input idle time for session killing is DISABLED
+~ - The forced "from" prepend on ingress keys is DISABLED
+~ - The following algorithms are allowed for ingress SSH keys: rsa, ecdsa, ed25519
+~ - The RSA key size for ingress SSH keys must be between 2048 and 8192 bits
+~ - The following algorithms are allowed for egress SSH keys: rsa, ecdsa, ed25519
+~ - The RSA key size for egress SSH keys must be between 2048 and 8192 bits
+~ - The Multi-Factor Authentication (MFA) policy is ENABLED
+~
+~ Here is your excuse for anything not working today:
+~ BOFH excuse #444:
+~ overflow error in /dev/null
+
+
+
+
+

Plugin configuration

+
+

Options

+
+
+admin_show_system_info (optional, boolean)
+

If enabled, bastion admins get more output regarding information of the +underlying OS. When omitted, this is enabled by default.

+
+ +
+
+show_fortune (optional, boolean)
+

If enabled, and if the fortune package is installed on your OS, +shows a fortune. When omitted, this is enabled by default.

+
+ +
+
+

Example

+

Configuration, in JSON format, must be in /etc/bastion/plugin.info.conf:

+
{ "admin_show_system_info": false, "show_fortune": false }
+
+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/lock.html b/plugins/open/lock.html new file mode 100644 index 0000000..be944ed --- /dev/null +++ b/plugins/open/lock.html @@ -0,0 +1,193 @@ + + + + + + + lock — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

lock

+
+

Manually lock all your current sessions

+
+

usage

+

--osh lock

+
+

This command will lock all your current sessions on this bastion instance. Note that this only applies to the bastion instance you're launching this command on, not on the whole bastion cluster (if you happen to have one).

+

To undo this action, you can use --osh unlock on the same instance.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/mtr.html b/plugins/open/mtr.html new file mode 100644 index 0000000..4557624 --- /dev/null +++ b/plugins/open/mtr.html @@ -0,0 +1,197 @@ + + + + + + + mtr — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

mtr

+
+

Runs the mtr tool to traceroute a host

+
+

usage

+

--osh mtr [--host] HOST [--report]

+
+
+
+--report
+

Don't run mtr interactively, output a text report once done

+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/nc.html b/plugins/open/nc.html new file mode 100644 index 0000000..5b19e42 --- /dev/null +++ b/plugins/open/nc.html @@ -0,0 +1,210 @@ + + + + + + + nc — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

nc

+
+

Check whether a remote TCP port is open

+
+

usage

+

--osh nc [--host] HOST [--port] PORT [-w TIMEOUT]

+
+
+
+--host HOST
+

Host or IP to attempt to connect to

+
+ +
+
+--port PORT
+

TCP port to attempt to connect to

+
+ +
+
+-w SECONDS
+

Timeout in seconds (default: 3)

+
+ +

Note that this is not a full-featured netcat, we just test whether a remote port is open. There is no way to exchange data using this command.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/ping.html b/plugins/open/ping.html new file mode 100644 index 0000000..9a69622 --- /dev/null +++ b/plugins/open/ping.html @@ -0,0 +1,221 @@ + + + + + + + ping — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

ping

+
+

Ping a remote host from the bastion

+
+

usage

+

--osh ping [--host HOST] [-c COUNT] [-s PKTSZ] [-t TTL] [-w TIMEOUT]

+
+
+
+--host HOST
+

Remote host to ping

+
+ +
+
+-c COUNT
+

Number of pings to send (default: infinite)

+
+ +
+
+-s SIZE
+

Specify the packet size to send

+
+ +
+
+-t TTL
+

TTL to set in the ICMP packet (default: OS dependent)

+
+ +
+
+-w TIMEOUT
+

Exit unconditionally after this amount of seconds (default & max: 86400)

+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/rsync.html b/plugins/open/rsync.html new file mode 100644 index 0000000..20ad16b --- /dev/null +++ b/plugins/open/rsync.html @@ -0,0 +1,206 @@ + + + + + + + rsync — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

rsync

+
+

Transfer files from/to remote servers using rsync through the bastion

+
+

Note

+

This plugin should not be called manually, but passed as the --rsh option to rsync.

+
+
+

Usage examples

+

To transfer all files from /srcdir to the remotehost's /dest/ directory:

+

The -va options are just examples, you can use any option of rsync that you see fit.

+

To transfer all remote files from /srcdir to the local /dest directory:

+

Please note that you need to be granted for uploading or downloading files +with rsync to/from the remote host, in addition to having the right to SSH to it. +For a group, the right should be added with --protocol rsync of the groupAddServer command. +For a personal access, the right should be added with --protocol rsync of the selfAddPersonalAccess command. +selfListEgressKeys

+

You'll find more information and examples in SFTP, SCP & RSYNC support.

+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/scp.html b/plugins/open/scp.html new file mode 100644 index 0000000..05e0a12 --- /dev/null +++ b/plugins/open/scp.html @@ -0,0 +1,209 @@ + + + + + + + scp — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

scp

+
+

Transfer files from/to remote servers using scp through the bastion

+
+

Note

+

This plugin generates a valid helper script for you to use the bastion over scp, read below to learn how to use it.

+
+

To be able to use scp over the bastion, you need to have a helper script that is specific +to your account on the bastion. This plugin's job is to generate it for you. +You can simply run it, and follow the guidelines.

+

Once this is done, you'll be able to scp through the bastion by adding -S SCP_SCRIPT to your +regular scp command, where SCP_SCRIPT is the location of the script you've just generated.

+

For example, to upload a file:

+
scp -S ~/scp_bastion localfile login@server:/dest/folder/
+
+
+

Or to recursively download a folder contents:

+
scp -S ~/scp_bastion -r login@server:/src/folder/ /tmp/
+
+
+

Please note that you need to be granted for uploading or downloading files +with scp to/from the remote host, in addition to having the right to SSH to it. +For a group, the right should be added with --scpup/--scpdown of the groupAddServer command. +For a personal access, the right should be added with --scpup/--scpdown of the selfAddPersonalAccess command.

+

You'll find more information and examples in SFTP, SCP & RSYNC support.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/selfAddIngressKey.html b/plugins/open/selfAddIngressKey.html new file mode 100644 index 0000000..618142d --- /dev/null +++ b/plugins/open/selfAddIngressKey.html @@ -0,0 +1,213 @@ + + + + + + + selfAddIngressKey — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

selfAddIngressKey

+
+

Add a new ingress public key to your account

+
+

usage

+

--osh selfAddIngressKey [--public-key '"ssh key text"'] [--piv]

+
+
+
+--public-key KEY
+

Your new ingress public SSH key to deposit on the bastion, use double-quoting if your're under a shell.

+
+

If this option is not specified, you'll be prompted interactively for your public SSH key. Note that you +can also pass it through STDIN directly. If the policy of this bastion allows it, you may prefix the key +with a 'from="IP1,IP2,..."' snippet, a la authorized_keys. However the policy might force a configured +'from' prefix that will override yours, or be used if you don't specify it yourself.

+
+
+ +
+
+--piv
+

Add a public SSH key from a PIV-compatible hardware token, along with its attestation certificate and key

+
+

certificate, both in PEM format. If you specified --public-key, then the attestation and key certificate are +expected on STDIN only, otherwise the public SSH key, the attestation and key certificate are expected on STDIN.

+
+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/selfDelIngressKey.html b/plugins/open/selfDelIngressKey.html new file mode 100644 index 0000000..954e017 --- /dev/null +++ b/plugins/open/selfDelIngressKey.html @@ -0,0 +1,204 @@ + + + + + + + selfDelIngressKey — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

selfDelIngressKey

+
+

Remove an ingress public key from your account

+
+

usage

+

--osh selfDelIngressKey [--id-to-delete|-l ID] [--fingerprint-to-delete|-f FP]

+
+
+
+-l, --id-to-delete ID
+

Directly specify key id to delete (CAUTION!), you can get id with selfListIngressKeys

+
+ +
+
+-f, --fingerprint-to-delete FP
+

Directly specify the fingerprint of the key to delete (CAUTION!)

+
+ +

If none of these options are specified, you'll be prompted interactively.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/selfForgetHostKey.html b/plugins/open/selfForgetHostKey.html new file mode 100644 index 0000000..7c32748 --- /dev/null +++ b/plugins/open/selfForgetHostKey.html @@ -0,0 +1,206 @@ + + + + + + + selfForgetHostKey — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

selfForgetHostKey

+
+

Forget a known host key from your bastion account

+
+

usage

+

--osh selfForgetHostKey [--host HOST] [--port PORT]

+
+
+
+--host HOST
+

Host to remove from the known_hosts file

+
+ +
+
+--port PORT
+

Port to look for in the known_hosts file (default: 22)

+
+ +

This command is useful to remove the man-in-the-middle warning when a key has changed, +however please verify that the host key change is legit before using this command. +The warning SSH gives is there for a reason.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/selfGenerateEgressKey.html b/plugins/open/selfGenerateEgressKey.html new file mode 100644 index 0000000..d61c573 --- /dev/null +++ b/plugins/open/selfGenerateEgressKey.html @@ -0,0 +1,222 @@ + + + + + + + selfGenerateEgressKey — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

selfGenerateEgressKey

+
+

Create a new public + private key pair on your bastion account

+
+

usage

+

--osh selfGenerateEgressKey --algo ALGO --size SIZE [--encrypted]

+
+
+
+--algo ALGO
+

Specifies the algo of the key, either rsa, ecdsa or ed25519.

+
+ +
+
+--size SIZE
+

Specifies the size of the key to be generated.

+
+

For RSA, choose between 2048 and 8192 (4096 is good). +For ECDSA, choose either 256, 384 or 521. +For ED25519, size is always 256.

+
+
+ +
+
+--encrypted
+

if specified, a passphrase will be prompted for the new key

+
+ +

A quick overview of the different algorithms:

+
Ed25519      : robustness[###] speed[###]
+ECDSA        : robustness[##.] speed[###]
+RSA          : robustness[#..] speed[#..]
+
+
+

This table is meant as a quick cheat-sheet, you're warmly advised to do +your own research, as other constraints may apply to your environment.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/selfGeneratePassword.html b/plugins/open/selfGeneratePassword.html new file mode 100644 index 0000000..789f136 --- /dev/null +++ b/plugins/open/selfGeneratePassword.html @@ -0,0 +1,212 @@ + + + + + + + selfGeneratePassword — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

selfGeneratePassword

+
+

Generate a new egress password for your account

+
+

usage

+

--osh selfGeneratePassword [--size SIZE] --do-it

+
+
+
+--size SIZE
+

Specify the number of characters of the password to generate

+
+ +
+
+--do-it
+

Required for the password to actually be generated, BEWARE: please read the note below

+
+ +

This plugin generates a new egress password to be used for ssh or telnet

+

NOTE: this is only needed for devices that don't support key-based SSH, +in most cases you should ignore this command completely, unless you +know that devices you need to access only support telnet or password-based SSH.

+

BEWARE: once a new password is generated this way, it'll be set as the new +egress password to use right away for your account, for any access that requires it. +A fallback mechanism exists that will auto-try the previous password if this one +doesn't work, but please ensure that this new password is deployed on the remote +devices as soon as possible.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/selfGenerateProxyPassword.html b/plugins/open/selfGenerateProxyPassword.html new file mode 100644 index 0000000..fb7bb65 --- /dev/null +++ b/plugins/open/selfGenerateProxyPassword.html @@ -0,0 +1,203 @@ + + + + + + + selfGenerateProxyPassword — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

selfGenerateProxyPassword

+
+

Generate a new ingress password to use the bastion HTTPS proxy

+
+

usage

+

--osh selfGenerateProxyPassword --do-it

+
+
+
+--do-it
+

Required for the password to actually be generated, BEWARE: please read the note below

+
+ +

This plugin generates a new ingress password to use the bastion HTTPS proxy.

+

NOTE: this is only needed for devices that only support HTTPS API and not ssh, +in most cases you should ignore this command completely, unless you +know that devices you need to access are using an HTTPS API.

+

BEWARE: once a new password is generated this way, it'll be set as the new +HTTPS proxy ingress password to use right away for your account.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/selfListAccesses.html b/plugins/open/selfListAccesses.html new file mode 100644 index 0000000..d90eff7 --- /dev/null +++ b/plugins/open/selfListAccesses.html @@ -0,0 +1,228 @@ + + + + + + + selfListAccesses — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

selfListAccesses

+
+

Show the list of servers you have access to

+
+

usage

+

--osh selfListAccesses [--hide-groups] [--reverse-dns]

+
+
+
+--hide-groups
+

Don't show the machines you have access to through group rights.

+
+

In other words, list only your personal accesses.

+
+
+ +
+
+--reverse-dns
+

Attempt to resolve the reverse hostnames (SLOW!)

+
+ +
+
+--include PATTERN
+

Only include accesses matching the given PATTERN (see below)

+
+

This option can be used multiple times to refine results

+
+
+ +
+
+--exclude PATTERN
+

Omit accesses matching the given PATTERN (see below)

+
+

This option can be used multiple times. +Note that --exclude takes precedence over --include

+
+
+ +

Note: PATTERN supports the * and ? wildcards. +If PATTERN is a simple string without wildcards, then names containing this string will be considered. +The matching is done on the text output of the command.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/selfListEgressKeys.html b/plugins/open/selfListEgressKeys.html new file mode 100644 index 0000000..fb69d5e --- /dev/null +++ b/plugins/open/selfListEgressKeys.html @@ -0,0 +1,195 @@ + + + + + + + selfListEgressKeys — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

selfListEgressKeys

+
+

List the public egress keys of your account

+
+

usage

+

--osh selfListEgressKeys

+
+

The keys listed are the public egress SSH keys tied to your account. +They can be used to gain access to another machine from this bastion, +by putting one of those keys in the remote machine's authorized_keys file, +and adding yourself access to this machine with selfAddPersonalAccess.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/selfListIngressKeys.html b/plugins/open/selfListIngressKeys.html new file mode 100644 index 0000000..91105f0 --- /dev/null +++ b/plugins/open/selfListIngressKeys.html @@ -0,0 +1,194 @@ + + + + + + + selfListIngressKeys — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

selfListIngressKeys

+
+

List the public ingress keys of your account

+
+

usage

+

--osh selfListIngressKeys

+
+

The keys listed are the public ingress SSH keys tied to your account. +Their private counterpart should be detained only by you, and used +to authenticate yourself to this bastion.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/selfListPasswords.html b/plugins/open/selfListPasswords.html new file mode 100644 index 0000000..dac84e7 --- /dev/null +++ b/plugins/open/selfListPasswords.html @@ -0,0 +1,192 @@ + + + + + + + selfListPasswords — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

selfListPasswords

+
+

List the hashes and metadata of the egress passwords associated to your account

+
+

usage

+

--osh selfListPasswords

+
+

The passwords corresponding to these hashes are only needed for devices that don't support key-based SSH

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/selfListSessions.html b/plugins/open/selfListSessions.html new file mode 100644 index 0000000..77b1d77 --- /dev/null +++ b/plugins/open/selfListSessions.html @@ -0,0 +1,277 @@ + + + + + + + selfListSessions — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

selfListSessions

+
+

List the few past sessions of your account

+
+

usage

+

--osh selfListSessions [OPTIONS]

+
+
+
+--detailed
+

Display more information about each session

+
+ +
+
+--limit LIMIT
+

Limit to LIMIT results

+
+ +
+
+--id ID
+

Only sessions having this ID

+
+ +
+
+--type TYPE
+

Only sessions of specified type (ssh, osh, ...)

+
+ +
+
+--allowed
+

Only sessions that have been allowed by the bastion

+
+ +
+
+--denied
+

Only sessions that have been denied by the bastion

+
+ +
+
+--after WHEN
+

Only sessions that started after WHEN,

+
+

WHEN can be a TIMESTAMP, or YYYY-MM-DD[@HH:MM:SS]

+
+
+ +
+
+--before WHEN
+

Only sessions that started before WHEN,

+
+

WHEN can be a TIMESTAMP, or YYYY-MM-DD[@HH:MM:SS]

+
+
+ +
+
+--host HOST
+

Only sessions connecting to remote HOST

+
+ +
+
+--to-port PORT
+

Only sessions connecting to remote PORT

+
+ +
+
+--user USER
+

Only sessions connecting using remote USER

+
+ +
+
+--via HOST
+

Only sessions that connected through bastion IP HOST

+
+ +
+
+--via-port PORT
+

Only sessions that connected through bastion PORT

+
+ +

Note that only the sessions that happened on this precise bastion instance will be shown, +not the sessions from its possible cluster siblings.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/selfMFAResetPassword.html b/plugins/open/selfMFAResetPassword.html new file mode 100644 index 0000000..d4170ea --- /dev/null +++ b/plugins/open/selfMFAResetPassword.html @@ -0,0 +1,193 @@ + + + + + + + selfMFAResetPassword — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

selfMFAResetPassword

+
+

Remove the UNIX password of your account

+
+

usage

+

--osh selfMFAResetPassword

+
+

Note that if your password is set, you'll be prompted for it. +Also note that this doesn't remove your UNIX password requirement, if set (see accountModify for this).

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/selfMFAResetTOTP.html b/plugins/open/selfMFAResetTOTP.html new file mode 100644 index 0000000..cc5a4c1 --- /dev/null +++ b/plugins/open/selfMFAResetTOTP.html @@ -0,0 +1,193 @@ + + + + + + + selfMFAResetTOTP — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

selfMFAResetTOTP

+
+

Remove the TOTP configuration of your account

+
+

usage

+

--osh selfMFAResetTOTP

+
+

Note that if your TOTP is set, you'll be prompted for it. +Also note that this doesn't remove your TOTP requirement, if set (see accountModify for this).

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/selfMFASetupPassword.html b/plugins/open/selfMFASetupPassword.html new file mode 100644 index 0000000..6a81562 --- /dev/null +++ b/plugins/open/selfMFASetupPassword.html @@ -0,0 +1,197 @@ + + + + + + + selfMFASetupPassword — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

selfMFASetupPassword

+
+

Setup an additional credential (UNIX password) to access your account

+
+

usage

+

--osh selfMFASetupPassword [--yes]

+
+
+
+--yes
+

Don't ask for confirmation

+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/selfMFASetupTOTP.html b/plugins/open/selfMFASetupTOTP.html new file mode 100644 index 0000000..2b72f74 --- /dev/null +++ b/plugins/open/selfMFASetupTOTP.html @@ -0,0 +1,197 @@ + + + + + + + selfMFASetupTOTP — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

selfMFASetupTOTP

+
+

Setup an additional credential (TOTP) to access your account

+
+

usage

+

--osh selfMFASetupTOTP [--no-confirm]

+
+
+
+--no-confirm
+

Bypass the confirmation step for TOTP enrollment phase

+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/selfPlaySession.html b/plugins/open/selfPlaySession.html new file mode 100644 index 0000000..6b6ab46 --- /dev/null +++ b/plugins/open/selfPlaySession.html @@ -0,0 +1,197 @@ + + + + + + + selfPlaySession — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

selfPlaySession

+
+

Replay the ttyrec of a past session

+
+

usage

+

--osh selfPlaySession --id ID

+
+
+
+--id ID
+

ID of the session to replay, use selfListSessions to find it.

+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/sftp.html b/plugins/open/sftp.html new file mode 100644 index 0000000..dcc1c2f --- /dev/null +++ b/plugins/open/sftp.html @@ -0,0 +1,212 @@ + + + + + + + sftp — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

sftp

+
+

Transfer files from/to remote servers using sftp through the bastion

+
+

Note

+

This plugin generates a valid helper script for you to use the bastion over scp, read below to learn how to use it.

+
+

To be able to use sftp over the bastion, you need to have a helper script that is specific +to your account on the bastion. This plugin's job is to generate it for you. +You can simply run it, and follow the guidelines.

+

Once this is done, you'll be able to sftp through the bastion by adding -S SFTP_SCRIPT to your +regular sftp command, where SFTP_SCRIPT is the location of the script you've just generated.

+

For example:

+
sftp -S ~/sftp_bastion login@server
+
+
+
+

Note

+

If you're getting the 'subsystem request failed on channel 0' error, it usually means that +sftp is not enabled on the remote server, as this is not always enabled by default, depending +on the distro you're using.

+
+

Please note that you need to be granted for uploading or downloading files +with SFTP to/from the remote host, in addition to having the right to SSH to it. +For a group, the right should be added with --sftp of the groupAddServer command. +For a personal access, the right should be added with --sftp of the selfAddPersonalAccess command. +selfListEgressKeys

+

You'll find more information and examples in SFTP, SCP & RSYNC support.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/open/unlock.html b/plugins/open/unlock.html new file mode 100644 index 0000000..869349c --- /dev/null +++ b/plugins/open/unlock.html @@ -0,0 +1,195 @@ + + + + + + + unlock — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

unlock

+
+

Unlock all your current sessions

+
+

usage

+

--osh unlock

+
+

This command will unlock all your current sessions on this bastion instance, +that were either locked for inactivity timeout or manually locked by you with lock. +Note that this only applies to the bastion instance you're launching this +command on, not on the whole bastion cluster (if you happen to have one).

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/accountAddPersonalAccess.html b/plugins/restricted/accountAddPersonalAccess.html new file mode 100644 index 0000000..968be8f --- /dev/null +++ b/plugins/restricted/accountAddPersonalAccess.html @@ -0,0 +1,293 @@ + + + + + + + accountAddPersonalAccess — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

accountAddPersonalAccess

+
+

Add a personal server access to an account

+
+

usage

+

--osh accountAddPersonalAccess --account ACCOUNT --host HOST --user USER --port PORT [OPTIONS]

+
+
+
+--account
+

Bastion account to add the access to

+
+ +
+
+--host HOST|IP|NET/CIDR
+
+

Host(s) to add access to, either a HOST which will be resolved to an IP immediately,

+
+

or an IP, or a whole network using the NET/CIDR notation

+
+
+
+
--user USER|PATTERN|* Specify which remote user should be allowed to connect as.

Globbing characters '*' and '?' are supported, so you can specify a pattern +that will be matched against the actual remote user name. +To allow any user, use '--user ' (you might need to escape '' from your shell)

+
+
--port PORT|* Remote port allowed to connect to

To allow any port, use '--port ' (you might need to escape '' from your shell)

+
+
+
+ +
+
+--protocol PROTO
+

Specify that a special protocol should be allowed for this HOST:PORT tuple, note that you

+
+

must not specify --user in that case. However, for this protocol to be usable under a given +remote user, access to the USER@HOST:PORT tuple must also be allowed. +PROTO must be one of: +scpup allow SCP upload, you--bastion-->server +scpdown allow SCP download, you<--bastion--server +sftp allow usage of the SFTP subsystem, through the bastion +rsync allow usage of rsync, through the bastion

+
+
+ +
+
+--force-key FINGERPRINT
+

Only use the key with the specified fingerprint to connect to the server (cf accountListEgressKeys)

+
+ +
+
+--force-password HASH
+

Only use the password with the specified hash to connect to the server (cf accountListPasswords)

+
+ +
+
+--ttl SECONDS|DURATION
+

Specify a number of seconds (or a duration string, such as "1d7h8m") after which the access will automatically expire

+
+ +
+
+--comment "'ANY TEXT'"
+

Add a comment alongside this server. Quote it twice as shown if you're under a shell.

+
+ +

The access will work only if one of the account's personal egress public key has been copied to the remote server. +To get the list of an account's personal egress public keys, see accountListEgressKeyss and selfListEgressKeys.

+
+
+

Plugin configuration

+
+

Options

+
+
+widest_v4_prefix (optional, integer, between 0 and 32)
+

When specified, this limits the size of prefixes that can be added to an +ACL, e.g. 24 would not allow prefixes wider than /24 (such as /20 or +/16). +Note that this doesn't prevent users from adding thousands of ACLs to +cover a wide range of networks, but this helps ensuring ACLs such as +0.0.0.0/0 can't be added in a single command.

+
+ +
+
+self_remote_user_only (optional, boolean)
+

When true, this only allows to add ACLs with the remote user being the +same than the account name, i.e. adding an access to a bastion account +named "johndoe" can only be done specifying this very account name as +the remote user name, with accountAddPersonalAccess --user johndoe.

+
+ +
+
+

Example

+

Configuration, in JSON format, must be in /etc/bastion/plugin.accountAddPersonalAccess.conf:

+
{ "widest_v4_prefix": 24, "self_remote_user_only": true }
+
+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/accountCreate.html b/plugins/restricted/accountCreate.html new file mode 100644 index 0000000..dc1afa3 --- /dev/null +++ b/plugins/restricted/accountCreate.html @@ -0,0 +1,264 @@ + + + + + + + accountCreate — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

accountCreate

+
+

Create a new bastion account

+
+

usage

+

--osh accountCreate --account ACCOUNT <--uid UID|--uid-auto> [OPTIONS]

+
+
+
+--account NAME
+

Account name to create, NAME must contain only valid UNIX account name characters

+
+ +
+
+--uid UID
+

Account system UID, also see --uid-auto

+
+ +
+
+--uid-auto
+

Auto-select an UID from the allowed range (the upper available one will be used)

+
+ +
+
+--always-active
+

This account's activation won't be challenged on connection, even if the bastion is globally

+
+

configured to check for account activation

+
+
+ +
+
+--osh-only
+

This account will only be able to use --osh commands, and can't connect anywhere through the bastion

+
+ +
+
+--max-inactive-days DAYS
+

Set account expiration policy, overriding the global bastion configuration 'accountMaxInactiveDays',

+
+

setting this option to zero disables account expiration.

+
+
+ +
+
+--immutable-key
+

Deny any subsequent modification of the account key (selfAddKey and selfDelKey are denied)

+
+ +
+
+--comment '"STRING"'
+

An optional comment when creating the account. Quote it twice as shown if you're under a shell.

+
+ +
+
+--public-key '"KEY"'
+

Account public SSH key to deposit on the bastion, if not present,

+
+

you'll be prompted interactively for it. Quote it twice as shown if your're under a shell.

+
+
+ +
+
+--no-key
+

Don't prompt for an SSH key, no ingress public key will be installed

+
+ +
+
+--ttl SECONDS|DURATION
+

Time after which the account will be deactivated (amount of seconds, or duration string such as "4d12h15m")

+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/accountDelPersonalAccess.html b/plugins/restricted/accountDelPersonalAccess.html new file mode 100644 index 0000000..d96f95d --- /dev/null +++ b/plugins/restricted/accountDelPersonalAccess.html @@ -0,0 +1,228 @@ + + + + + + + accountDelPersonalAccess — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

accountDelPersonalAccess

+
+

Remove a personal server access from an account

+
+

usage

+

--osh accountDelPersonalAccess --account ACCOUNT --host HOST --user USER --port PORT [OPTIONS]

+
+
+
+--account
+

Bastion account to remove access from

+
+ +
+
+--host HOST|IP|NET/CIDR
+
+

Host(s) to remove access from, either a HOST which will be resolved to an IP immediately,

+
+

or an IP, or a whole network using the NET/CIDR notation

+
+
+
+
--user USER|PATTERN|* Specify which remote user was allowed to connect as.

Globbing characters '*' and '?' are supported, so you can specify a pattern +that will be matched against the actual remote user name. +If any user was allowed, use '--user ' (you might need to escape '' from your shell)

+
+
--port PORT|* Remote port that was allowed to connect to

If any port was allowed, use '--port ' (you might need to escape '' from your shell)

+
+
+
+ +
+
+--protocol PROTO
+

Specify that a special protocol allowance should be removed from this HOST:PORT tuple, note that you

+
+

must not specify --user in that case. +PROTO must be one of: +scpup allow SCP upload, you--bastion-->server +scpdown allow SCP download, you<--bastion--server +sftp allow usage of the SFTP subsystem, through the bastion +rsync allow usage of rsync, through the bastion

+
+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/accountDelete.html b/plugins/restricted/accountDelete.html new file mode 100644 index 0000000..8e1d937 --- /dev/null +++ b/plugins/restricted/accountDelete.html @@ -0,0 +1,201 @@ + + + + + + + accountDelete — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

accountDelete

+
+

Delete an account from the bastion

+
+

usage

+

--osh accountDelete --account ACCOUNT

+
+
+
+--account ACCOUNT
+

Account name to delete

+
+ +
+
+--no-confirm
+

Don't ask for confirmation, and blame yourself if you deleted the wrong account

+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/accountFreeze.html b/plugins/restricted/accountFreeze.html new file mode 100644 index 0000000..3923c4a --- /dev/null +++ b/plugins/restricted/accountFreeze.html @@ -0,0 +1,204 @@ + + + + + + + accountFreeze — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

accountFreeze

+
+

Freeze an account, to prevent it from connecting

+
+

usage

+

--osh accountFreeze --account ACCOUNT [--reason "'SOME REASON'"]

+
+
+
+--account ACCOUNT
+

Account to freeze

+
+ +
+
+--reason  "'SOME REASON'"
+

Optional reason for the account to be frozen (will be displayed to the user),

+
+

if you are in a shell (and not in interactive mode), quote it twice as shown.

+
+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/accountGeneratePassword.html b/plugins/restricted/accountGeneratePassword.html new file mode 100644 index 0000000..00e40e5 --- /dev/null +++ b/plugins/restricted/accountGeneratePassword.html @@ -0,0 +1,216 @@ + + + + + + + accountGeneratePassword — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

accountGeneratePassword

+
+

Generate a new egress password for an account

+
+

usage

+

--osh accountGeneratePassword --account ACCOUNT [--size SIZE] --do-it

+
+
+
+--account ACCOUNT
+

Specify which account you want to generate a password for

+
+ +
+
+--size    SIZE
+

Specify the number of characters of the password to generate

+
+ +
+
+--do-it
+

Required for the password to actually be generated, BEWARE: please read the note below

+
+ +

This plugin generates a new egress password to be used for ssh or telnet

+

NOTE: this is only needed for devices that don't support key-based SSH, +in most cases you should ignore this command completely, unless you +know that devices you need to access only support telnet or password-based SSH.

+

BEWARE: once a new password is generated this way, it'll be set as the new +egress password to use right away for the account, for any access that requires it. +A fallback mechanism exists that will auto-try the previous password if this one +doesn't work, but please ensure that this new password is deployed on the remote +devices as soon as possible.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/accountGrantCommand.html b/plugins/restricted/accountGrantCommand.html new file mode 100644 index 0000000..382518e --- /dev/null +++ b/plugins/restricted/accountGrantCommand.html @@ -0,0 +1,206 @@ + + + + + + + accountGrantCommand — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

accountGrantCommand

+
+

Grant access to a restricted command

+
+

usage

+

--osh accountGrantCommand --account ACCOUNT --command COMMAND

+
+
+
+--account ACCOUNT
+

Bastion account to work on

+
+ +
+
+--command COMMAND
+

The name of the OSH plugin to grant (omit to get the list)

+
+ +

Note that accountGrantCommand being a restricted command as any other, you can grant it to somebody else, +but then they'll be able to grant themselves or anybody else to this or any other restricted command.

+

A specific command that can be granted is auditor, it is not an osh plugin per-se, but activates +more verbose output for several other commands, suitable to audit rights or grants without needing +to be granted (e.g. to groups).

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/accountInfo.html b/plugins/restricted/accountInfo.html new file mode 100644 index 0000000..3e7896d --- /dev/null +++ b/plugins/restricted/accountInfo.html @@ -0,0 +1,297 @@ + + + + + + + accountInfo — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

accountInfo

+
+

Display some information about an account

+
+

usage

+

--osh accountInfo <--account ACCOUNT|--all> [OPTIONS]

+
+
+
+--account ACCOUNT
+

The account name to work on

+
+ +
+
+--all
+

Dump info for all accounts (auditors only), use with --json

+
+ +
+
+--with[out]-everything
+

Include or exclude all below options, including future ones

+
+ +
+
+--with[out]-groups
+

Whether to include the groups the account has a role on (SLOW, default: no)

+
+ +
+
+--with[out]-mfa-password-info
+

Whether to include MFA password info of the account (SLOW, auditors only, default: no)

+
+ +
+
+--with[out]-egress-keys
+

Whether to include the account's egress keys (SLOW, auditors only, default: no)

+
+ +
+
+

Usage examples

+

Show info about a specific account:

+
--osh accountInfo --account jdoe12
+
+
+

Gather info about all accounts, with no extra data except their egress keys:

+
--osh accountInfo --all --without-everything --with-egress-keys --json
+
+
+

Gather info about all accounts, including all extra data (and possibly future options):

+
--osh accountInfo --all --with-everything --json
+
+
+
+
+

Output example

+
│ user1 is a bastion admin
+│ user1 is a bastion superowner
+│ user1 is a bastion auditor
+│
+│ user1 has access to the following restricted commands:
+│ - accountCreate
+│ - accountDelete
+│ - groupCreate
+│ - groupDelete
+│
+│ This account is part of the following groups:
+│         testgroup1 Owner GateKeeper ACLKeeper Member     -
+│    gatekeeper-grp2 Owner GateKeeper         -      -     -
+│
+│ This account is active
+│ This account has no TTL set
+│ This account is not frozen
+│ This account has seen recent-enough activity to not be activity-expired
+│ As a consequence, this account can connect to this bastion
+│
+│ Last seen on Thu 2023-03-16 07:51:49 UTC (00:00:00 ago)
+│ Created on Fri 2022-06-17 09:52:50 UTC (271d+21:58:59 ago)
+│ Created by jdoe
+│ Created using The Bastion v3.08.01
+│
+│ Account egress SSH config:
+│ - (default)
+│
+│ PIV-enforced policy for ingress keys on this account is enabled
+│
+│ Account Multi-Factor Authentication status:
+│ - Additional password authentication is not required for this account
+│ - Additional password authentication bypass is disabled for this account
+│ - Additional password authentication is enabled and active
+│ - Additional TOTP authentication is not required for this account
+│ - Additional TOTP authentication bypass is disabled for this account
+│ - Additional TOTP authentication is disabled
+│ - PAM authentication bypass is disabled
+│ - Optional public key authentication is disabled
+│ - MFA policy on personal accesses (using personal keys) on egress side is: password
+│
+│ - Account is immune to idle counter-measures: no
+│ - Maximum number of days of inactivity before account is disabled: (default)
+│
+│ Account PAM UNIX password information (used for password MFA):
+│ - Password is set
+│ - Password was last changed on 2023-01-27
+│ - Password must be changed every 90 days at least
+│ - A warning is displayed 75 days before expiration
+│ - Account will not be disabled after password expiration
+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/accountList.html b/plugins/restricted/accountList.html new file mode 100644 index 0000000..ea2b00a --- /dev/null +++ b/plugins/restricted/accountList.html @@ -0,0 +1,240 @@ + + + + + + + accountList — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

accountList

+
+

List the bastion accounts

+
+

usage

+

--osh accountList [OPTIONS]

+
+
+
+--account ACCOUNT
+

Only list the specified account. This is an easy way to check whether the account exists

+
+ +
+
+--inactive-only
+

Only list inactive accounts

+
+ +
+
+--audit
+

Show more verbose information (SLOW!), you need to be a bastion auditor

+
+ +
+
+--no-password-info
+

Don't gather password info in audit mode (makes --audit way faster)

+
+ +
+
+--no-output
+

Don't print human-readable output (faster, use with --json)

+
+ +
+
+--include PATTERN
+

Only show accounts whose name match the given PATTERN (see below)

+
+

This option can be used multiple times to refine results

+
+
+ +
+
+--exclude PATTERN
+

Omit accounts whose name match the given PATTERN (see below)

+
+

This option can be used multiple times. +Note that --exclude takes precedence over --include

+
+
+ +

Note: PATTERN supports the * and ? wildcards. +If PATTERN is a simple string without wildcards, then names containing this string will be considered.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/accountListAccesses.html b/plugins/restricted/accountListAccesses.html new file mode 100644 index 0000000..9e436a6 --- /dev/null +++ b/plugins/restricted/accountListAccesses.html @@ -0,0 +1,232 @@ + + + + + + + accountListAccesses — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

accountListAccesses

+
+

View the expanded access list of a given bastion account

+
+

usage

+

--osh accountListAccesses --account ACCOUNT [--hide-groups] [--reverse-dns]

+
+
+
+--account ACCOUNT
+

The account to work on

+
+ +
+
+--hide-groups
+

Don't show the machines the accouns has access to through group rights.

+
+

In other words, list only the account's personal accesses.

+
+
+ +
+
+--reverse-dns
+

Attempt to resolve the reverse hostnames (SLOW!)

+
+ +
+
+--include PATTERN
+

Only include accesses matching the given PATTERN (see below)

+
+

This option can be used multiple times to refine results

+
+
+ +
+
+--exclude PATTERN
+

Omit accesses matching the given PATTERN (see below)

+
+

This option can be used multiple times. +Note that --exclude takes precedence over --include

+
+
+ +

Note: PATTERN supports the * and ? wildcards. +If PATTERN is a simple string without wildcards, then names containing this string will be considered. +The matching is done on the text output of the command.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/accountListEgressKeys.html b/plugins/restricted/accountListEgressKeys.html new file mode 100644 index 0000000..31b7a97 --- /dev/null +++ b/plugins/restricted/accountListEgressKeys.html @@ -0,0 +1,199 @@ + + + + + + + accountListEgressKeys — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

accountListEgressKeys

+
+

List the public egress keys of an account

+
+

usage

+

--osh accountListEgressKeys --account ACCOUNT

+
+
+
+--account ACCOUNT
+

Account to display the public egress keys of

+
+ +

The keys listed are the public egress SSH keys tied to this account. +They can be used to gain access to another machine from this bastion, +by putting one of those keys in the remote machine's authorized_keys file, +and adding this account access to this machine with accountAddPersonalAccess.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/accountListIngressKeys.html b/plugins/restricted/accountListIngressKeys.html new file mode 100644 index 0000000..3c2ef21 --- /dev/null +++ b/plugins/restricted/accountListIngressKeys.html @@ -0,0 +1,198 @@ + + + + + + + accountListIngressKeys — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

accountListIngressKeys

+
+

List the public ingress keys of an account

+
+

usage

+

--osh accountListIngressKeys --account ACCOUNT

+
+
+
+--account ACCOUNT
+

Account to list the keys of

+
+ +

The keys listed are the public ingress SSH keys tied to this account. +Their private counterpart should be detained only by this account's user, +so that they can to authenticate themselves to this bastion.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/accountListPasswords.html b/plugins/restricted/accountListPasswords.html new file mode 100644 index 0000000..7e49903 --- /dev/null +++ b/plugins/restricted/accountListPasswords.html @@ -0,0 +1,196 @@ + + + + + + + accountListPasswords — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

accountListPasswords

+
+

List the hashes and metadata of the egress passwords associated to an account

+
+

usage

+

--osh accountListPasswords --account ACCOUNT

+
+
+
+--account ACCOUNT
+

The account name to work on

+
+ +

The passwords corresponding to these hashes are only needed for devices that don't support key-based SSH

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/accountMFAResetPassword.html b/plugins/restricted/accountMFAResetPassword.html new file mode 100644 index 0000000..c380b0e --- /dev/null +++ b/plugins/restricted/accountMFAResetPassword.html @@ -0,0 +1,196 @@ + + + + + + + accountMFAResetPassword — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

accountMFAResetPassword

+
+

Remove the UNIX password of an account

+
+

usage

+

--osh accountMFAResetPassword --account ACCOUNT

+
+
+
+--account ACCOUNT
+

Specify which account you want to remove the UNIX password of

+
+ +

Note that if doesn't remove the account UNIX password requirement, if set (see accountModify for this)

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/accountMFAResetTOTP.html b/plugins/restricted/accountMFAResetTOTP.html new file mode 100644 index 0000000..580a89b --- /dev/null +++ b/plugins/restricted/accountMFAResetTOTP.html @@ -0,0 +1,196 @@ + + + + + + + accountMFAResetTOTP — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

accountMFAResetTOTP

+
+

Remove the TOTP configuration of an account

+
+

usage

+

--osh accountMFAResetTOTP --account ACCOUNT

+
+
+
+--account ACCOUNT
+

Specify which account you want to remove the TOTP configuration of

+
+ +

Note that if doesn't remove the TOTP requirement, if set (see accountModify for this).

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/accountModify.html b/plugins/restricted/accountModify.html new file mode 100644 index 0000000..2ad783a --- /dev/null +++ b/plugins/restricted/accountModify.html @@ -0,0 +1,300 @@ + + + + + + + accountModify — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

accountModify

+
+

Modify an account configuration

+
+

usage

+

--osh accountModify --account ACCOUNT [--option value [--option value [...]]]

+
+
+
+--account ACCOUNT
+

Bastion account to work on

+
+ +
+
+--pam-auth-bypass yes|no
+

Enable or disable PAM auth bypass for this account in addition to pubkey auth (default is 'no'),

+
+

in that case sshd will not rely at all on PAM auth and /etc/pam.d/sshd configuration. This +does not change the behaviour of the code, just the PAM auth handled by SSH itself

+
+
+ +
+
+--mfa-password-required yes|no|bypass
+

Enable or disable UNIX password requirement for this account in addition to pubkey auth (default is 'no'),

+
+

this overrides the global bastion configuration 'accountMFAPolicy'. If 'bypass' is specified, +no password will ever be asked, even for groups or plugins explicitly requiring it

+
+
+ +
+
+--mfa-totp-required yes|no|bypass
+

Enable or disable TOTP requirement for this account in addition to pubkey auth (default is 'no'),

+
+

this overrides the global bastion configuration 'accountMFAPolicy'. If 'bypass' is specified, +no OTP will ever be asked, even for groups or plugins explicitly requiring it

+
+
+ +
+
+--egress-strict-host-key-checking POLICY
+

Modify the egress SSH behavior of this account regarding StrictHostKeyChecking (see man ssh_config),

+
+

POLICY can be 'yes', 'accept-new', 'no', 'ask', 'default' or 'bypass'. +'bypass' means setting StrictHostKeyChecking=no and UserKnownHostsFile=/dev/null, +which will permit egress connections in all cases, even when host keys change all the time on the same target. +This effectively suppress the host key checking entirely. Please don't enable this blindly. +'default' will remove this account's StrictHostKeyChecking setting override. +All the other policies carry the same meaning that what is documented in man ssh_config.

+
+
+ +
+
+--egress-session-multiplexing POLICY
+

Modify the egress SSH behavior of this account regarding ControlMaster and ControlPath. POLICY can be:

+
+

'yes', setting ControlMaster to 'auto' and setting ControlPath properly for session sharing, +'no', setting ControlMaster to 'no' and ControlPath to 'none', +'default', removing this account ControlMaster and ControlPath overrides altogether.

+
+
+ +
+
+--personal-egress-mfa-required POLICY
+

Enforce UNIX password requirement, or TOTP requirement, or any MFA requirement, when connecting to a server

+
+

using the personal keys of the account, POLICY can be 'password', 'totp', 'any' or 'none'

+
+
+ +
+
+--always-active yes|no
+

Set or unset the account as always active (i.e. disable the check of the 'active' status on this account)

+
+ +
+
+--idle-ignore yes|no
+

If enabled, this account is immune to the idleLockTimeout and idleKillTimeout bastion-wide policy

+
+ +
+
+--max-inactive-days DAYS
+

Set account expiration policy, overriding the global bastion configuration 'accountMaxInactiveDays'.

+
+

Setting this option to zero disables account expiration. Setting this option to -1 removes this account +expiration policy, i.e. the global bastion setting will apply.

+
+
+ +
+
+--osh-only yes|no
+

If enabled, this account can only use --osh commands, and can't connect anywhere through the bastion

+
+ +
+
+--pubkey-auth-optional yes|no
+

Make the public key optional on ingress for the account (default is 'no').

+
+

When enabled the public key part of the authentication becomes optional when a password and/or TOTP is defined, +allowing to login with just the password/TOTP. If no password/TOTP is defined then the public key is the only way to authenticate, +because some form of authentication is always required. +When disabled, the public key is always required. +Egress is not affected.

+
+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/accountPIV.html b/plugins/restricted/accountPIV.html new file mode 100644 index 0000000..19baed2 --- /dev/null +++ b/plugins/restricted/accountPIV.html @@ -0,0 +1,233 @@ + + + + + + + accountPIV — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

accountPIV

+
+

Modify the PIV policy for the ingress keys of an account

+
+

usage

+

--osh accountPIV --account ACCOUNT --policy <default|enforce|never|grace --ttl SECONDS|DURATION>

+
+
+
+--account ACCOUNT
+

Bastion account to work on

+
+ +
+
+--policy  POLICY
+

Changes the PIV policy of account. See below for a description of available policies.

+
+ +
+
+--ttl SECONDS|DURATION
+

For the grace policy, amount of time after which the account will automatically revert

+
+

to its previous policy (amount of seconds, or duration string such as "4d12h15m").

+
+
+ +
+

Possible POLICY values:

+
+
default

No specific policy is defined for this account, the default bastion policy applies (see the ingressRequirePIV global option).

+
+
enforce

Only verified PIV keys can be added as ingress SSH keys for this account. Note that setting the policy to enforce also immediately +disables any non-PIV keys from the account's ingress keys. If no valid PIV key is found, this in effect disables all the keys of said +account, preventing connection. The disabled keys are still kept so that setting back the policy to default or never does restore +the non-PIV keys.

+
+
never

Regardless of the global configuration of the bastion (see the ingressRequirePIV global option), this account will never be required +to use only PIV keys. This can be needed for a non-human account if PIV is enabled bastion-wide.

+
+
grace

enables temporary deactivation of PIV enforcement on this account. This is only meaningful when the policy is already set to enforce +for this account, or if the global ingressRequirePIV option is set to true. This policy requires the use of the --ttl option to +specify how much time the policy will be relaxed for this account before going back to its previous policy automatically. This can be +useful when people forget their PIV-enabled hardware token and you don't want to send them back home.

+
+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/accountRevokeCommand.html b/plugins/restricted/accountRevokeCommand.html new file mode 100644 index 0000000..728f3ce --- /dev/null +++ b/plugins/restricted/accountRevokeCommand.html @@ -0,0 +1,201 @@ + + + + + + + accountRevokeCommand — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

accountRevokeCommand

+
+

Revoke access to a restricted command

+
+

usage

+

--osh accountRevokeCommand --account ACCOUNT --command COMMAND

+
+
+
+--account ACCOUNT
+

Bastion account to work on

+
+ +
+
+--command COMMAND
+

The name of the OSH plugin to revoke access to (omit to get the list)

+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/accountUnexpire.html b/plugins/restricted/accountUnexpire.html new file mode 100644 index 0000000..54c97d1 --- /dev/null +++ b/plugins/restricted/accountUnexpire.html @@ -0,0 +1,197 @@ + + + + + + + accountUnexpire — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

accountUnexpire

+
+

Unexpire an inactivity-expired account

+
+

usage

+

--osh accountUnexpire --account ACCOUNT

+
+
+
+--account ACCOUNT
+

Account to work on

+
+ +

When the bastion is configured to expire accounts that haven't been seen in a while, +this command can be used to activate them back.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/accountUnfreeze.html b/plugins/restricted/accountUnfreeze.html new file mode 100644 index 0000000..6e060f2 --- /dev/null +++ b/plugins/restricted/accountUnfreeze.html @@ -0,0 +1,195 @@ + + + + + + + accountUnfreeze — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

accountUnfreeze

+
+

Unfreeze a frozen account

+
+

usage

+

--osh accountUnfreeze --account ACCOUNT

+
+
+
+--account ACCOUNT
+

Account to unfreeze

+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/accountUnlock.html b/plugins/restricted/accountUnlock.html new file mode 100644 index 0000000..aa10cbb --- /dev/null +++ b/plugins/restricted/accountUnlock.html @@ -0,0 +1,195 @@ + + + + + + + accountUnlock — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

accountUnlock

+
+

Unlock an account locked by pam_tally, pam_tally2 or pam_faillock

+
+

usage

+

--osh accountUnlock --account ACCOUNT

+
+
+
+--account ACCOUNT
+

Account to work on

+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/groupCreate.html b/plugins/restricted/groupCreate.html new file mode 100644 index 0000000..7ea96aa --- /dev/null +++ b/plugins/restricted/groupCreate.html @@ -0,0 +1,241 @@ + + + + + + + groupCreate — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

groupCreate

+
+

Create a group

+
+

usage

+

--osh groupCreate --group GROUP --owner ACCOUNT <--algo ALGO --size SIZE [--encrypted]|--no-key>

+
+
+
+--group
+

Group name to create

+
+ +
+
+--owner
+

Preexisting bastion account to assign as owner (can be you)

+
+ +
+
+--encrypted
+

Add a passphrase to the key. Beware that you'll have to enter it for each use.

+
+

Do NOT add the passphrase after this option, you'll be prompted interactively for it.

+
+
+ +
+
+--algo
+

Specifies the algo of the key, either rsa, ecdsa or ed25519.

+
+ +
+
+--size
+

Specifies the size of the key to be generated.

+
+

For RSA, choose between 2048 and 8192 (4096 is good). +For ECDSA, choose either 256, 384 or 521. +For ED25519, size is always 256.

+
+
+ +
+
+--no-key
+

Don't generate an egress SSH key at all for this group

+
+ +

A quick overview of the different algorithms:

+
Ed25519      : robustness[###] speed[###]
+ECDSA        : robustness[##.] speed[###]
+RSA          : robustness[#..] speed[#..]
+
+
+

This table is meant as a quick cheat-sheet, you're warmly advised to do +your own research, as other constraints may apply to your environment.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/groupDelete.html b/plugins/restricted/groupDelete.html new file mode 100644 index 0000000..3d81dd8 --- /dev/null +++ b/plugins/restricted/groupDelete.html @@ -0,0 +1,203 @@ + + + + + + + groupDelete — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

groupDelete

+
+

Delete a group

+
+

usage

+

--osh groupDelete --group GROUP

+
+
+
+--group GROUP
+

Group name to delete

+
+ +
+
+--no-confirm
+

Skip group name confirmation, but blame yourself if you deleted the wrong group!

+
+ +

This restricted command is able to delete any group. Group owners can however delete +their own groups using the sibling groupDestroy command.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/index.html b/plugins/restricted/index.html new file mode 100644 index 0000000..2ce27f0 --- /dev/null +++ b/plugins/restricted/index.html @@ -0,0 +1,321 @@ + + + + + + + restricted plugins — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

restricted plugins

+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/realmCreate.html b/plugins/restricted/realmCreate.html new file mode 100644 index 0000000..0897df1 --- /dev/null +++ b/plugins/restricted/realmCreate.html @@ -0,0 +1,219 @@ + + + + + + + realmCreate — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

realmCreate

+
+

Declare and create a new trusted realm

+
+

usage

+

--osh realmCreate --realm REALM --from IP1,IP2 [OPTIONS]

+
+
+
+--realm   REALM
+

Realm name to create

+
+ +
+
+--comment STRING
+

An optional comment when creating the realm. Double-quote if you're under a shell.

+
+ +
+
+--from
+

IP1,IP2 Comma-separated list of outgoing IPs used by the realm we're declaring (i.e. IPs used by the bastion(s) on the other side)

+
+

the expected format is the one used by the from="" directive on SSH keys (IP and prefixes are supported)

+
+
+ +
+
+--public-key KEY
+

Public SSH key to deposit on the bastion to access this realm. If not present,

+
+

you'll be prompted interactively for it. Use double-quoting if your're under a shell.

+
+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/realmDelete.html b/plugins/restricted/realmDelete.html new file mode 100644 index 0000000..f51de67 --- /dev/null +++ b/plugins/restricted/realmDelete.html @@ -0,0 +1,195 @@ + + + + + + + realmDelete — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

realmDelete

+
+

Delete a bastion realm

+
+

usage

+

--osh realmDelete --realm REALM

+
+
+
+--realm REALM
+

Name of the realm to delete

+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/realmInfo.html b/plugins/restricted/realmInfo.html new file mode 100644 index 0000000..6883970 --- /dev/null +++ b/plugins/restricted/realmInfo.html @@ -0,0 +1,195 @@ + + + + + + + realmInfo — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

realmInfo

+
+

Display information about a bastion realm

+
+

usage

+

--osh realmInfo --realm REALM

+
+
+
+--realm REALM
+

Name of the realm to show info about

+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/realmList.html b/plugins/restricted/realmList.html new file mode 100644 index 0000000..6a77f83 --- /dev/null +++ b/plugins/restricted/realmList.html @@ -0,0 +1,195 @@ + + + + + + + realmList — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

realmList

+
+

List the bastions realms

+
+

usage

+

--osh realmList [--realm REALM]

+
+
+
+--realm REALM
+

Only list the specified realm (mainly: check if it exists)

+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/rootListIngressKeys.html b/plugins/restricted/rootListIngressKeys.html new file mode 100644 index 0000000..bf70f8a --- /dev/null +++ b/plugins/restricted/rootListIngressKeys.html @@ -0,0 +1,192 @@ + + + + + + + rootListIngressKeys — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

rootListIngressKeys

+
+

List the public keys to connect as root on this bastion

+
+

usage

+

--osh rootListIngressKeys

+
+

This command is mainly useful for auditability purposes. +As it gives some information as to who can be root on the underlying system, +please grant this command only to accounts that need to have this information.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/selfAddPersonalAccess.html b/plugins/restricted/selfAddPersonalAccess.html new file mode 100644 index 0000000..25a201f --- /dev/null +++ b/plugins/restricted/selfAddPersonalAccess.html @@ -0,0 +1,290 @@ + + + + + + + selfAddPersonalAccess — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

selfAddPersonalAccess

+
+

Add a personal server access to your account

+
+

usage

+

--osh selfAddPersonalAccess --host HOST --user USER --port PORT [OPTIONS]

+
+
+
+--host HOST|IP|NET/CIDR
+
+

Host(s) to add access to, either a HOST which will be resolved to an IP immediately,

+
+

or an IP, or a whole network using the NET/CIDR notation

+
+
+
+
--user USER|PATTERN|* Specify which remote user should be allowed to connect as.

Globbing characters '*' and '?' are supported, so you can specify a pattern +that will be matched against the actual remote user name. +To allow any user, use '--user ' (you might need to escape '' from your shell)

+
+
--port PORT|* Remote port allowed to connect to

To allow any port, use '--port ' (you might need to escape '' from your shell)

+
+
+
+ +
+
+--protocol PROTO
+

Specify that a special protocol should be allowed for this HOST:PORT tuple, note that you

+
+

must not specify --user in that case. However, for this protocol to be usable under a given +remote user, access to the USER@HOST:PORT tuple must also be allowed. +PROTO must be one of: +scpup allow SCP upload, you--bastion-->server +scpdown allow SCP download, you<--bastion--server +sftp allow usage of the SFTP subsystem, through the bastion +rsync allow usage of rsync, through the bastion

+
+
+ +
+
+--force
+

Add the access without checking that the public SSH key is properly installed remotely

+
+ +
+
+--force-key FINGERPRINT
+

Only use the key with the specified fingerprint to connect to the server (cf selfListEgressKeys)

+
+ +
+
+--force-password HASH
+

Only use the password with the specified hash to connect to the server (cf selfListPasswords)

+
+ +
+
+--ttl SECONDS|DURATION
+

Specify a number of seconds (or a duration string, such as "1d7h8m") after which the access will automatically expire

+
+ +
+
+--comment "'ANY TEXT'"
+

Add a comment alongside this server. Quote it twice as shown if you're under a shell.

+
+ +
+
+

Plugin configuration

+
+

Options

+
+
+widest_v4_prefix (optional, integer, between 0 and 32)
+

When specified, this limits the size of prefixes that can be added to an +ACL, e.g. 24 would not allow prefixes wider than /24 (such as /20 or +/16). +Note that this doesn't prevent users from adding thousands of ACLs to +cover a wide range of networks, but this helps ensuring ACLs such as +0.0.0.0/0 can't be added in a single command.

+
+ +
+
+self_remote_user_only (optional, boolean)
+

When true, this only allows to add ACLs with the remote user being the +same than the account name, i.e. a bastion account named "johndoe" would +only be able to use selfAddPersonalAccess --user johndoe.

+
+ +
+
+

Example

+

Configuration, in JSON format, must be in /etc/bastion/plugin.selfAddPersonalAccess.conf:

+
{ "widest_v4_prefix": 24, "self_remote_user_only": true }
+
+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/selfDelPersonalAccess.html b/plugins/restricted/selfDelPersonalAccess.html new file mode 100644 index 0000000..5e12f04 --- /dev/null +++ b/plugins/restricted/selfDelPersonalAccess.html @@ -0,0 +1,222 @@ + + + + + + + selfDelPersonalAccess — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

selfDelPersonalAccess

+
+

Remove a personal server access from your account

+
+

usage

+

--osh selfDelPersonalAccess --host HOST --user USER --port PORT [OPTIONS]

+
+
+
+--host HOST|IP|NET/CIDR
+
+

Host(s) to remove access from, either a HOST which will be resolved to an IP immediately,

+
+

or an IP, or a whole network using the NET/CIDR notation

+
+
+
+
--user USER|PATTERN|* Specify which remote user was allowed to connect as.

Globbing characters '*' and '?' are supported, so you can specify a pattern +that will be matched against the actual remote user name. +If any user was allowed, use '--user ' (you might need to escape '' from your shell)

+
+
--port PORT|* Remote port that was allowed to connect to

If any port was allowed, use '--port ' (you might need to escape '' from your shell)

+
+
+
+ +
+
+--protocol PROTO
+

Specify that a special protocol allowance should be removed from this HOST:PORT tuple, note that you

+
+

must not specify --user in that case. +PROTO must be one of: +scpup allow SCP upload, you--bastion-->server +scpdown allow SCP download, you<--bastion--server +sftp allow usage of the SFTP subsystem, through the bastion +rsync allow usage of rsync, through the bastion

+
+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/plugins/restricted/whoHasAccessTo.html b/plugins/restricted/whoHasAccessTo.html new file mode 100644 index 0000000..2b6bd2b --- /dev/null +++ b/plugins/restricted/whoHasAccessTo.html @@ -0,0 +1,233 @@ + + + + + + + whoHasAccessTo — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

whoHasAccessTo

+
+

List the accounts that have access to a given server

+
+

usage

+

--osh whoHasAccessTo --host SERVER [OPTIONS]

+
+
+
+--host SERVER
+

List declared accesses to this server

+
+ +
+
+--user USER
+

Remote user allowed (if not specified, ignore user specifications)

+
+ +
+
+--port PORT
+

Remote port allowed (if not specified, ignore port specifications)

+
+ +
+
+--ignore-personal
+

Don't check accounts' personal accesses (i.e. only check groups)

+
+ +
+
+--ignore-group GROUP
+

Ignore accesses by this group, if you know GROUP public key is in fact

+
+

not present on remote server but bastion thinks it is

+
+
+ +
+
+--show-wildcards
+

Also list accesses that match because 0.0.0.0/0 is listed in a group or private access,

+
+

this is disabled by default because this is almost always just noise (see Note below)

+
+
+ +

Note: This list is what the bastion THINKS is true, which means that if some group has 0.0.0.0/0 in its list, +then it'll show all the members of that group as having access to the machine you're specifying, through this group key. +This is only true if the remote server does have the group key installed, of course, which the bastion +can't tell without trying to connect "right now" (which it won't do).

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/presentation/features.html b/presentation/features.html new file mode 100644 index 0000000..4c3e78f --- /dev/null +++ b/presentation/features.html @@ -0,0 +1,176 @@ + + + + + + + Features — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Features

+
+

Note

+

This aims to be a quick overview of the main supported features of The Bastion, focusing on use cases. +For a better introduction about the basic features, please refer to the front page of the documentation.

+
+
+

Warning

+

Documentation might not be present yet for all the features below.

+
+
    +

  • Personal and group access schemes with group roles delegation to ensure teams autonomy without security trade-offs

    • +

  • SSH protocol break between the ingress and egress connections (see other security measures)

    • +

  • Self-reliance achieved through virtually no external dependencies (see other security measures)

    • +

  • Interactive session recording (in standard ttyrec files)

    • +

  • Non-interactive session recording (stdout and stderr through ttyrec)

    • +

  • Extensive logging support through syslog for easy SIEM consumption

    • +

  • Supports MOSH on the ingress connection side

    • +

  • Supports scp passthrough, to upload and/or download files from/to remote servers

    • +

  • Supports netconf SSH subsystem passthrough

    • +

  • Supports Yubico PIV keys +attestation checking and enforcement +on the ingress connection side

    • +

  • Supports realms, to create a trust between two bastions of possibly two different companies, +splitting the authentication and authorization phases while still enforcing local policies

    • +

  • Supports SSH password autologin on the egress side for legacy devices not supporting pubkey authentication, +while still forcing proper pubkey authentication on the ingress side

    • +

  • Supports telnet password autologin on the egress side for ancient devices not supporting SSH, +while still forcing proper SSH pubkey authentication on the ingress side

    • +

  • Supports HTTPS proxying with man-in-the-middle authentication and authorization handling, +for ingress and egress password decoupling (mainly useful for network device APIs)

    • +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/presentation/principles.html b/presentation/principles.html new file mode 100644 index 0000000..f6a594b --- /dev/null +++ b/presentation/principles.html @@ -0,0 +1,156 @@ + + + + + + + Principles — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Principles

+
+

Note

+

Most of the principles of The Bastion are well explained in the Part 2 of the blog post +that announced the release. The links are below.

+
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/presentation/security.html b/presentation/security.html new file mode 100644 index 0000000..be4ff58 --- /dev/null +++ b/presentation/security.html @@ -0,0 +1,227 @@ + + + + + + + Security — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Security

+
+

Security principles at the core

+

Even with the most conservative, precautionous and paranoid coding process, code has bugs, +so it shouldn't be trusted blindly. Hence the bastion doesn't trust its own code. +It leverages the operating system security primitives to get additional security, as seen below.

+
    +

  • Uses the well-known and trusted UNIX Discretionary Access Control:

    +
    +
      +

    • Bastion users are mapped to actual system users

      • +

    • Bastion groups are mapped to actual system groups

      • +

    • All the code is constantly checking rights before allowing any action

      • +

    • UNIX DAC is used as a safety belt to prevent an action from succeeding even if the code +is tricked into allowing it

      • +
    +
    +
    • +

  • The bastion main script is declared as the bastion user's system shell:

    +
    +
      +

    • No user has real (bash-like) shell access on the system

      • +

    • All code is ran under the unprivileged user's system account rights

      • +

    • Even if a user could escape to a real shell, they wouldn't be able to connect to machines they don't have +access to, because they don't have filesystem-level read access to the SSH keys

      • +
    +
    +
    • +

  • The code is modular

    +
    +
      +

    • The main code mainly checks rights, logs actions, and enable ssh access to other machines

      • +

    • All side commands, called plugins, are in modules separated from the main code

      • +

    • The modules can either be open or restricted

      +
      +
        +

      • Only accounts that have been specifically granted on a need-to-use basis can run a specific restricted plugin

        • +

      • This is checked by the code, and also enforced by UNIX DAC (the plugin is only readable and +executable by the system group specific to the plugin)

        • +
      +
      +
      • +
    +
    +
    • +

  • All the code needing extended system privileges is separated from the main code, in modules called helpers

    +
    +
      +

    • Helpers are run exclusively under sudo

      • +

    • The sudoers configuration is attached to a system group specific to the command, +which is granted to accounts on a need-to-use basis

      • +

    • The helpers are only readable and executable by the system group specific to the command

      • +

    • The helpers path and some of their immutable parameters are hardcoded in the sudoers configuration

      • +

    • Perl tainted mode (-T) is used for all code running under sudo, preventing any user-input to +interfere with the logic, by halting execution immediately

      • +

    • Code running under sudo doesn't trust its caller and re-checks every input

      • +

    • Communication between unprivileged and privileged-code are done using JSON

      • +
    +
    +
    • +
+
+
+

Auditability

+
    +

  • Bastion administrators must use the bastion's logic to connect to itself to administer it (or better, +use another bastion to do so), this ensures auditability in all cases

    • +

  • Every access and action (whether allowed or denied) is logged with:

    +
    +
      +

    • syslog, which should also be sent to a remote syslog server to ensure even +bastion administrators can't tamper their tracks, and/or

      • +

    • local sqlite3 databases for easy searching

      • +
    +
    +
    • +

  • This code is used in production in several PCI-DSS, ISO 27001, SOC1 and SOC2 certified environments

    • +
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/search.html b/search.html new file mode 100644 index 0000000..fdef649 --- /dev/null +++ b/search.html @@ -0,0 +1,156 @@ + + + + + + Search — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+
    +
  • »
    • +
  • Search
    • +
  • +
    • +
+
+
+
+
+ + + + +
+ +
+ +
+
+ +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/searchindex.js b/searchindex.js new file mode 100644 index 0000000..cddff23 --- /dev/null +++ b/searchindex.js @@ -0,0 +1 @@ +Search.setIndex({docnames:["administration/configuration/bastion_conf","administration/configuration/index","administration/configuration/osh-backup-acl-keys_conf","administration/configuration/osh-cleanup-guest-key-access_conf","administration/configuration/osh-encrypt-rsync_conf","administration/configuration/osh-http-proxy_conf","administration/configuration/osh-lingering-sessions-reaper_conf","administration/configuration/osh-orphaned-homedir_conf","administration/configuration/osh-piv-grace-reaper_conf","administration/configuration/osh-remove-empty-folders_conf","administration/configuration/osh-sync-watcher_sh","administration/logs","administration/mfa","administration/security_advisories","administration/security_advisories/cve_2023_45140","development/setup","development/tests","faq","index","installation/advanced","installation/basic","installation/docker","installation/restoring_from_backup","installation/upgrading","plugins/admin/adminMaintenance","plugins/admin/adminSudo","plugins/admin/index","plugins/group-aclkeeper/groupAddServer","plugins/group-aclkeeper/groupDelServer","plugins/group-aclkeeper/groupSetServers","plugins/group-aclkeeper/index","plugins/group-gatekeeper/groupAddGuestAccess","plugins/group-gatekeeper/groupAddMember","plugins/group-gatekeeper/groupDelGuestAccess","plugins/group-gatekeeper/groupDelMember","plugins/group-gatekeeper/groupListGuestAccesses","plugins/group-gatekeeper/index","plugins/group-owner/groupAddAclkeeper","plugins/group-owner/groupAddGatekeeper","plugins/group-owner/groupAddOwner","plugins/group-owner/groupDelAclkeeper","plugins/group-owner/groupDelEgressKey","plugins/group-owner/groupDelGatekeeper","plugins/group-owner/groupDelOwner","plugins/group-owner/groupDestroy","plugins/group-owner/groupGenerateEgressKey","plugins/group-owner/groupGeneratePassword","plugins/group-owner/groupModify","plugins/group-owner/groupTransmitOwnership","plugins/group-owner/index","plugins/open/alive","plugins/open/batch","plugins/open/clush","plugins/open/groupInfo","plugins/open/groupList","plugins/open/groupListPasswords","plugins/open/groupListServers","plugins/open/help","plugins/open/index","plugins/open/info","plugins/open/lock","plugins/open/mtr","plugins/open/nc","plugins/open/ping","plugins/open/rsync","plugins/open/scp","plugins/open/selfAddIngressKey","plugins/open/selfDelIngressKey","plugins/open/selfForgetHostKey","plugins/open/selfGenerateEgressKey","plugins/open/selfGeneratePassword","plugins/open/selfGenerateProxyPassword","plugins/open/selfListAccesses","plugins/open/selfListEgressKeys","plugins/open/selfListIngressKeys","plugins/open/selfListPasswords","plugins/open/selfListSessions","plugins/open/selfMFAResetPassword","plugins/open/selfMFAResetTOTP","plugins/open/selfMFASetupPassword","plugins/open/selfMFASetupTOTP","plugins/open/selfPlaySession","plugins/open/sftp","plugins/open/unlock","plugins/restricted/accountAddPersonalAccess","plugins/restricted/accountCreate","plugins/restricted/accountDelPersonalAccess","plugins/restricted/accountDelete","plugins/restricted/accountFreeze","plugins/restricted/accountGeneratePassword","plugins/restricted/accountGrantCommand","plugins/restricted/accountInfo","plugins/restricted/accountList","plugins/restricted/accountListAccesses","plugins/restricted/accountListEgressKeys","plugins/restricted/accountListIngressKeys","plugins/restricted/accountListPasswords","plugins/restricted/accountMFAResetPassword","plugins/restricted/accountMFAResetTOTP","plugins/restricted/accountModify","plugins/restricted/accountPIV","plugins/restricted/accountRevokeCommand","plugins/restricted/accountUnexpire","plugins/restricted/accountUnfreeze","plugins/restricted/accountUnlock","plugins/restricted/groupCreate","plugins/restricted/groupDelete","plugins/restricted/index","plugins/restricted/realmCreate","plugins/restricted/realmDelete","plugins/restricted/realmInfo","plugins/restricted/realmList","plugins/restricted/rootListIngressKeys","plugins/restricted/selfAddPersonalAccess","plugins/restricted/selfDelPersonalAccess","plugins/restricted/whoHasAccessTo","presentation/features","presentation/principles","presentation/security","using/api","using/basics/access_management","using/basics/first_steps","using/basics/index","using/http_proxy","using/piv","using/sftp_scp_rsync","using/specific_ssh_clients_tutorials/index","using/specific_ssh_clients_tutorials/putty"],envversion:{"sphinx.domains.c":2,"sphinx.domains.changeset":1,"sphinx.domains.citation":1,"sphinx.domains.cpp":4,"sphinx.domains.index":1,"sphinx.domains.javascript":2,"sphinx.domains.math":2,"sphinx.domains.python":3,"sphinx.domains.rst":2,"sphinx.domains.std":2,sphinx:56},filenames:["administration/configuration/bastion_conf.rst","administration/configuration/index.rst","administration/configuration/osh-backup-acl-keys_conf.rst","administration/configuration/osh-cleanup-guest-key-access_conf.rst","administration/configuration/osh-encrypt-rsync_conf.rst","administration/configuration/osh-http-proxy_conf.rst","administration/configuration/osh-lingering-sessions-reaper_conf.rst","administration/configuration/osh-orphaned-homedir_conf.rst","administration/configuration/osh-piv-grace-reaper_conf.rst","administration/configuration/osh-remove-empty-folders_conf.rst","administration/configuration/osh-sync-watcher_sh.rst","administration/logs.rst","administration/mfa.rst","administration/security_advisories.rst","administration/security_advisories/cve_2023_45140.rst","development/setup.rst","development/tests.rst","faq.rst","index.rst","installation/advanced.rst","installation/basic.rst","installation/docker.rst","installation/restoring_from_backup.rst","installation/upgrading.rst","plugins/admin/adminMaintenance.rst","plugins/admin/adminSudo.rst","plugins/admin/index.rst","plugins/group-aclkeeper/groupAddServer.rst","plugins/group-aclkeeper/groupDelServer.rst","plugins/group-aclkeeper/groupSetServers.rst","plugins/group-aclkeeper/index.rst","plugins/group-gatekeeper/groupAddGuestAccess.rst","plugins/group-gatekeeper/groupAddMember.rst","plugins/group-gatekeeper/groupDelGuestAccess.rst","plugins/group-gatekeeper/groupDelMember.rst","plugins/group-gatekeeper/groupListGuestAccesses.rst","plugins/group-gatekeeper/index.rst","plugins/group-owner/groupAddAclkeeper.rst","plugins/group-owner/groupAddGatekeeper.rst","plugins/group-owner/groupAddOwner.rst","plugins/group-owner/groupDelAclkeeper.rst","plugins/group-owner/groupDelEgressKey.rst","plugins/group-owner/groupDelGatekeeper.rst","plugins/group-owner/groupDelOwner.rst","plugins/group-owner/groupDestroy.rst","plugins/group-owner/groupGenerateEgressKey.rst","plugins/group-owner/groupGeneratePassword.rst","plugins/group-owner/groupModify.rst","plugins/group-owner/groupTransmitOwnership.rst","plugins/group-owner/index.rst","plugins/open/alive.rst","plugins/open/batch.rst","plugins/open/clush.rst","plugins/open/groupInfo.rst","plugins/open/groupList.rst","plugins/open/groupListPasswords.rst","plugins/open/groupListServers.rst","plugins/open/help.rst","plugins/open/index.rst","plugins/open/info.rst","plugins/open/lock.rst","plugins/open/mtr.rst","plugins/open/nc.rst","plugins/open/ping.rst","plugins/open/rsync.rst","plugins/open/scp.rst","plugins/open/selfAddIngressKey.rst","plugins/open/selfDelIngressKey.rst","plugins/open/selfForgetHostKey.rst","plugins/open/selfGenerateEgressKey.rst","plugins/open/selfGeneratePassword.rst","plugins/open/selfGenerateProxyPassword.rst","plugins/open/selfListAccesses.rst","plugins/open/selfListEgressKeys.rst","plugins/open/selfListIngressKeys.rst","plugins/open/selfListPasswords.rst","plugins/open/selfListSessions.rst","plugins/open/selfMFAResetPassword.rst","plugins/open/selfMFAResetTOTP.rst","plugins/open/selfMFASetupPassword.rst","plugins/open/selfMFASetupTOTP.rst","plugins/open/selfPlaySession.rst","plugins/open/sftp.rst","plugins/open/unlock.rst","plugins/restricted/accountAddPersonalAccess.rst","plugins/restricted/accountCreate.rst","plugins/restricted/accountDelPersonalAccess.rst","plugins/restricted/accountDelete.rst","plugins/restricted/accountFreeze.rst","plugins/restricted/accountGeneratePassword.rst","plugins/restricted/accountGrantCommand.rst","plugins/restricted/accountInfo.rst","plugins/restricted/accountList.rst","plugins/restricted/accountListAccesses.rst","plugins/restricted/accountListEgressKeys.rst","plugins/restricted/accountListIngressKeys.rst","plugins/restricted/accountListPasswords.rst","plugins/restricted/accountMFAResetPassword.rst","plugins/restricted/accountMFAResetTOTP.rst","plugins/restricted/accountModify.rst","plugins/restricted/accountPIV.rst","plugins/restricted/accountRevokeCommand.rst","plugins/restricted/accountUnexpire.rst","plugins/restricted/accountUnfreeze.rst","plugins/restricted/accountUnlock.rst","plugins/restricted/groupCreate.rst","plugins/restricted/groupDelete.rst","plugins/restricted/index.rst","plugins/restricted/realmCreate.rst","plugins/restricted/realmDelete.rst","plugins/restricted/realmInfo.rst","plugins/restricted/realmList.rst","plugins/restricted/rootListIngressKeys.rst","plugins/restricted/selfAddPersonalAccess.rst","plugins/restricted/selfDelPersonalAccess.rst","plugins/restricted/whoHasAccessTo.rst","presentation/features.rst","presentation/principles.rst","presentation/security.rst","using/api.rst","using/basics/access_management.rst","using/basics/first_steps.rst","using/basics/index.rst","using/http_proxy.rst","using/piv.rst","using/sftp_scp_rsync.rst","using/specific_ssh_clients_tutorials/index.rst","using/specific_ssh_clients_tutorials/putty.rst"],objects:{accountAddPersonalAccess:[[84,0,1,"cmdoption-accountAddPersonalAccess-account","--account"],[84,0,1,"cmdoption-accountAddPersonalAccess-comment","--comment"],[84,0,1,"cmdoption-accountAddPersonalAccess-force-key","--force-key"],[84,0,1,"cmdoption-accountAddPersonalAccess-force-password","--force-password"],[84,0,1,"cmdoption-accountAddPersonalAccess-host","--host"],[84,0,1,"cmdoption-accountAddPersonalAccess-protocol","--protocol"],[84,0,1,"cmdoption-accountAddPersonalAccess-ttl","--ttl"],[84,0,1,"cmdoption-accountAddPersonalAccess-arg-widest_v4_prefix","between"],[84,0,1,"cmdoption-accountAddPersonalAccess-arg-self_remote_user_only","boolean)"],[84,0,1,"cmdoption-accountAddPersonalAccess-arg-widest_v4_prefix","integer"],[84,0,1,"cmdoption-accountAddPersonalAccess-arg-self_remote_user_only","self_remote_user_only"],[84,0,1,"cmdoption-accountAddPersonalAccess-arg-widest_v4_prefix","widest_v4_prefix"]],accountCreate:[[85,0,1,"cmdoption-accountCreate-account","--account"],[85,0,1,"cmdoption-accountCreate-always-active","--always-active"],[85,0,1,"cmdoption-accountCreate-comment","--comment"],[85,0,1,"cmdoption-accountCreate-immutable-key","--immutable-key"],[85,0,1,"cmdoption-accountCreate-max-inactive-days","--max-inactive-days"],[85,0,1,"cmdoption-accountCreate-no-key","--no-key"],[85,0,1,"cmdoption-accountCreate-osh-only","--osh-only"],[85,0,1,"cmdoption-accountCreate-public-key","--public-key"],[85,0,1,"cmdoption-accountCreate-ttl","--ttl"],[85,0,1,"cmdoption-accountCreate-uid","--uid"],[85,0,1,"cmdoption-accountCreate-uid-auto","--uid-auto"]],accountDelPersonalAccess:[[86,0,1,"cmdoption-accountDelPersonalAccess-account","--account"],[86,0,1,"cmdoption-accountDelPersonalAccess-host","--host"],[86,0,1,"cmdoption-accountDelPersonalAccess-protocol","--protocol"]],accountDelete:[[87,0,1,"cmdoption-accountDelete-account","--account"],[87,0,1,"cmdoption-accountDelete-no-confirm","--no-confirm"]],accountFreeze:[[88,0,1,"cmdoption-accountFreeze-account","--account"],[88,0,1,"cmdoption-accountFreeze-reason","--reason"]],accountGeneratePassword:[[89,0,1,"cmdoption-accountGeneratePassword-account","--account"],[89,0,1,"cmdoption-accountGeneratePassword-do-it","--do-it"],[89,0,1,"cmdoption-accountGeneratePassword-size","--size"]],accountGrantCommand:[[90,0,1,"cmdoption-accountGrantCommand-account","--account"],[90,0,1,"cmdoption-accountGrantCommand-command","--command"]],accountInfo:[[91,0,1,"cmdoption-accountInfo-account","--account"],[91,0,1,"cmdoption-accountInfo-all","--all"],[91,0,1,"cmdoption-accountInfo-with-out-egress-keys","--with[out]-egress-keys"],[91,0,1,"cmdoption-accountInfo-with-out-everything","--with[out]-everything"],[91,0,1,"cmdoption-accountInfo-with-out-groups","--with[out]-groups"],[91,0,1,"cmdoption-accountInfo-with-out-mfa-password-info","--with[out]-mfa-password-info"]],accountList:[[92,0,1,"cmdoption-accountList-account","--account"],[92,0,1,"cmdoption-accountList-audit","--audit"],[92,0,1,"cmdoption-accountList-exclude","--exclude"],[92,0,1,"cmdoption-accountList-inactive-only","--inactive-only"],[92,0,1,"cmdoption-accountList-include","--include"],[92,0,1,"cmdoption-accountList-no-output","--no-output"],[92,0,1,"cmdoption-accountList-no-password-info","--no-password-info"]],accountListAccesses:[[93,0,1,"cmdoption-accountListAccesses-account","--account"],[93,0,1,"cmdoption-accountListAccesses-exclude","--exclude"],[93,0,1,"cmdoption-accountListAccesses-hide-groups","--hide-groups"],[93,0,1,"cmdoption-accountListAccesses-include","--include"],[93,0,1,"cmdoption-accountListAccesses-reverse-dns","--reverse-dns"]],accountListEgressKeys:[[94,0,1,"cmdoption-accountListEgressKeys-account","--account"]],accountListIngressKeys:[[95,0,1,"cmdoption-accountListIngressKeys-account","--account"]],accountListPasswords:[[96,0,1,"cmdoption-accountListPasswords-account","--account"]],accountMFAResetPassword:[[97,0,1,"cmdoption-accountMFAResetPassword-account","--account"]],accountMFAResetTOTP:[[98,0,1,"cmdoption-accountMFAResetTOTP-account","--account"]],accountModify:[[99,0,1,"cmdoption-accountModify-account","--account"],[99,0,1,"cmdoption-accountModify-always-active","--always-active"],[99,0,1,"cmdoption-accountModify-egress-session-multiplexing","--egress-session-multiplexing"],[99,0,1,"cmdoption-accountModify-egress-strict-host-key-checking","--egress-strict-host-key-checking"],[99,0,1,"cmdoption-accountModify-idle-ignore","--idle-ignore"],[99,0,1,"cmdoption-accountModify-max-inactive-days","--max-inactive-days"],[99,0,1,"cmdoption-accountModify-mfa-password-required","--mfa-password-required"],[99,0,1,"cmdoption-accountModify-mfa-totp-required","--mfa-totp-required"],[99,0,1,"cmdoption-accountModify-osh-only","--osh-only"],[99,0,1,"cmdoption-accountModify-pam-auth-bypass","--pam-auth-bypass"],[99,0,1,"cmdoption-accountModify-personal-egress-mfa-required","--personal-egress-mfa-required"],[99,0,1,"cmdoption-accountModify-pubkey-auth-optional","--pubkey-auth-optional"]],accountPIV:[[100,0,1,"cmdoption-accountPIV-account","--account"],[100,0,1,"cmdoption-accountPIV-policy","--policy"],[100,0,1,"cmdoption-accountPIV-ttl","--ttl"]],accountRevokeCommand:[[101,0,1,"cmdoption-accountRevokeCommand-account","--account"],[101,0,1,"cmdoption-accountRevokeCommand-command","--command"]],accountUnexpire:[[102,0,1,"cmdoption-accountUnexpire-account","--account"]],accountUnfreeze:[[103,0,1,"cmdoption-accountUnfreeze-account","--account"]],accountUnlock:[[104,0,1,"cmdoption-accountUnlock-account","--account"]],adminMaintenance:[[24,0,1,"cmdoption-adminMaintenance-lock","--lock"],[24,0,1,"cmdoption-adminMaintenance-message","--message"],[24,0,1,"cmdoption-adminMaintenance-unlock","--unlock"]],adminSudo:[[25,0,1,"cmdoption-adminSudo-sudo-as","--sudo-as"],[25,0,1,"cmdoption-adminSudo-sudo-cmd","--sudo-cmd"]],alive:[[50,0,1,"cmdoption-alive-host","--host"]],clush:[[52,0,1,"cmdoption-clush-command","--command"],[52,0,1,"cmdoption-clush-list","--list"],[52,0,1,"cmdoption-clush-no-confirm","--no-confirm"],[52,0,1,"cmdoption-clush-no-pause-on-failure","--no-pause-on-failure"],[52,0,1,"cmdoption-clush-port","--port"],[52,0,1,"cmdoption-clush-step-by-step","--step-by-step"],[52,0,1,"cmdoption-clush-user","--user"]],groupAddAclkeeper:[[37,0,1,"cmdoption-groupAddAclkeeper-account","--account"],[37,0,1,"cmdoption-groupAddAclkeeper-group","--group"]],groupAddGatekeeper:[[38,0,1,"cmdoption-groupAddGatekeeper-account","--account"],[38,0,1,"cmdoption-groupAddGatekeeper-group","--group"]],groupAddGuestAccess:[[31,0,1,"cmdoption-groupAddGuestAccess-account","--account"],[31,0,1,"cmdoption-groupAddGuestAccess-comment","--comment"],[31,0,1,"cmdoption-groupAddGuestAccess-group","--group"],[31,0,1,"cmdoption-groupAddGuestAccess-host","--host"],[31,0,1,"cmdoption-groupAddGuestAccess-protocol","--protocol"],[31,0,1,"cmdoption-groupAddGuestAccess-ttl","--ttl"]],groupAddMember:[[32,0,1,"cmdoption-groupAddMember-account","--account"],[32,0,1,"cmdoption-groupAddMember-group","--group"]],groupAddOwner:[[39,0,1,"cmdoption-groupAddOwner-account","--account"],[39,0,1,"cmdoption-groupAddOwner-group","--group"]],groupAddServer:[[27,0,1,"cmdoption-groupAddServer-comment","--comment"],[27,0,1,"cmdoption-groupAddServer-force","--force"],[27,0,1,"cmdoption-groupAddServer-force-key","--force-key"],[27,0,1,"cmdoption-groupAddServer-force-password","--force-password"],[27,0,1,"cmdoption-groupAddServer-group","--group"],[27,0,1,"cmdoption-groupAddServer-host","--host"],[27,0,1,"cmdoption-groupAddServer-protocol","--protocol"],[27,0,1,"cmdoption-groupAddServer-ttl","--ttl"]],groupCreate:[[105,0,1,"cmdoption-groupCreate-algo","--algo"],[105,0,1,"cmdoption-groupCreate-encrypted","--encrypted"],[105,0,1,"cmdoption-groupCreate-group","--group"],[105,0,1,"cmdoption-groupCreate-no-key","--no-key"],[105,0,1,"cmdoption-groupCreate-owner","--owner"],[105,0,1,"cmdoption-groupCreate-size","--size"]],groupDelAclkeeper:[[40,0,1,"cmdoption-groupDelAclkeeper-account","--account"],[40,0,1,"cmdoption-groupDelAclkeeper-group","--group"]],groupDelEgressKey:[[41,0,1,"cmdoption-groupDelEgressKey-group","--group"],[41,0,1,"cmdoption-groupDelEgressKey-id","--id"]],groupDelGatekeeper:[[42,0,1,"cmdoption-groupDelGatekeeper-account","--account"],[42,0,1,"cmdoption-groupDelGatekeeper-group","--group"]],groupDelGuestAccess:[[33,0,1,"cmdoption-groupDelGuestAccess-account","--account"],[33,0,1,"cmdoption-groupDelGuestAccess-group","--group"],[33,0,1,"cmdoption-groupDelGuestAccess-host","--host"],[33,0,1,"cmdoption-groupDelGuestAccess-protocol","--protocol"]],groupDelMember:[[34,0,1,"cmdoption-groupDelMember-account","--account"],[34,0,1,"cmdoption-groupDelMember-group","--group"]],groupDelOwner:[[43,0,1,"cmdoption-groupDelOwner-account","--account"],[43,0,1,"cmdoption-groupDelOwner-group","--group"]],groupDelServer:[[28,0,1,"cmdoption-groupDelServer-group","--group"],[28,0,1,"cmdoption-groupDelServer-host","--host"],[28,0,1,"cmdoption-groupDelServer-protocol","--protocol"]],groupDelete:[[106,0,1,"cmdoption-groupDelete-group","--group"],[106,0,1,"cmdoption-groupDelete-no-confirm","--no-confirm"]],groupDestroy:[[44,0,1,"cmdoption-groupDestroy-group","--group"],[44,0,1,"cmdoption-groupDestroy-no-confirm","--no-confirm"]],groupGenerateEgressKey:[[45,0,1,"cmdoption-groupGenerateEgressKey-algo","--algo"],[45,0,1,"cmdoption-groupGenerateEgressKey-encrypted","--encrypted"],[45,0,1,"cmdoption-groupGenerateEgressKey-group","--group"],[45,0,1,"cmdoption-groupGenerateEgressKey-size","--size"]],groupGeneratePassword:[[46,0,1,"cmdoption-groupGeneratePassword-do-it","--do-it"],[46,0,1,"cmdoption-groupGeneratePassword-group","--group"],[46,0,1,"cmdoption-groupGeneratePassword-size","--size"]],groupInfo:[[53,0,1,"cmdoption-groupInfo-all","--all"],[53,0,1,"cmdoption-groupInfo-group","--group"],[53,0,1,"cmdoption-groupInfo-with-out-everything","--with[out]-everything"],[53,0,1,"cmdoption-groupInfo-with-out-keys","--with[out]-keys"]],groupList:[[54,0,1,"cmdoption-groupList-all","--all"],[54,0,1,"cmdoption-groupList-exclude","--exclude"],[54,0,1,"cmdoption-groupList-include","--include"]],groupListGuestAccesses:[[35,0,1,"cmdoption-groupListGuestAccesses-account","--account"],[35,0,1,"cmdoption-groupListGuestAccesses-exclude","--exclude"],[35,0,1,"cmdoption-groupListGuestAccesses-group","--group"],[35,0,1,"cmdoption-groupListGuestAccesses-include","--include"],[35,0,1,"cmdoption-groupListGuestAccesses-reverse-dns","--reverse-dns"]],groupListPasswords:[[55,0,1,"cmdoption-groupListPasswords-group","--group"]],groupListServers:[[56,0,1,"cmdoption-groupListServers-exclude","--exclude"],[56,0,1,"cmdoption-groupListServers-group","--group"],[56,0,1,"cmdoption-groupListServers-include","--include"],[56,0,1,"cmdoption-groupListServers-reverse-dns","--reverse-dns"]],groupModify:[[47,0,1,"cmdoption-groupModify-group","--group"],[47,0,1,"cmdoption-groupModify-guest-ttl-limit","--guest-ttl-limit"],[47,0,1,"cmdoption-groupModify-mfa-required","--mfa-required"]],groupSetServers:[[29,0,1,"cmdoption-groupSetServers-dry-run","--dry-run"],[29,0,1,"cmdoption-groupSetServers-group","--group"],[29,0,1,"cmdoption-groupSetServers-skip-errors","--skip-errors"]],groupTransmitOwnership:[[48,0,1,"cmdoption-groupTransmitOwnership-account","--account"],[48,0,1,"cmdoption-groupTransmitOwnership-group","--group"]],info:[[59,0,1,"cmdoption-info-arg-admin_show_system_info","admin_show_system_info"],[59,0,1,"cmdoption-info-arg-show_fortune","boolean)"],[59,0,1,"cmdoption-info-arg-show_fortune","show_fortune"]],mtr:[[61,0,1,"cmdoption-mtr-report","--report"]],nc:[[62,0,1,"cmdoption-nc-host","--host"],[62,0,1,"cmdoption-nc-port","--port"],[62,0,1,"cmdoption-nc-w","-w"]],ping:[[63,0,1,"cmdoption-ping-host","--host"],[63,0,1,"cmdoption-ping-c","-c"],[63,0,1,"cmdoption-ping-s","-s"],[63,0,1,"cmdoption-ping-t","-t"],[63,0,1,"cmdoption-ping-w","-w"]],realmCreate:[[108,0,1,"cmdoption-realmCreate-comment","--comment"],[108,0,1,"cmdoption-realmCreate-from","--from"],[108,0,1,"cmdoption-realmCreate-public-key","--public-key"],[108,0,1,"cmdoption-realmCreate-realm","--realm"]],realmDelete:[[109,0,1,"cmdoption-realmDelete-realm","--realm"]],realmInfo:[[110,0,1,"cmdoption-realmInfo-realm","--realm"]],realmList:[[111,0,1,"cmdoption-realmList-realm","--realm"]],selfAddIngressKey:[[66,0,1,"cmdoption-selfAddIngressKey-piv","--piv"],[66,0,1,"cmdoption-selfAddIngressKey-public-key","--public-key"]],selfAddPersonalAccess:[[113,0,1,"cmdoption-selfAddPersonalAccess-comment","--comment"],[113,0,1,"cmdoption-selfAddPersonalAccess-force","--force"],[113,0,1,"cmdoption-selfAddPersonalAccess-force-key","--force-key"],[113,0,1,"cmdoption-selfAddPersonalAccess-force-password","--force-password"],[113,0,1,"cmdoption-selfAddPersonalAccess-host","--host"],[113,0,1,"cmdoption-selfAddPersonalAccess-protocol","--protocol"],[113,0,1,"cmdoption-selfAddPersonalAccess-ttl","--ttl"],[113,0,1,"cmdoption-selfAddPersonalAccess-arg-widest_v4_prefix","between"],[113,0,1,"cmdoption-selfAddPersonalAccess-arg-self_remote_user_only","boolean)"],[113,0,1,"cmdoption-selfAddPersonalAccess-arg-widest_v4_prefix","integer"],[113,0,1,"cmdoption-selfAddPersonalAccess-arg-self_remote_user_only","self_remote_user_only"],[113,0,1,"cmdoption-selfAddPersonalAccess-arg-widest_v4_prefix","widest_v4_prefix"]],selfDelIngressKey:[[67,0,1,"cmdoption-selfDelIngressKey-f","--fingerprint-to-delete"],[67,0,1,"cmdoption-selfDelIngressKey-l","--id-to-delete"],[67,0,1,"cmdoption-selfDelIngressKey-f","-f"],[67,0,1,"cmdoption-selfDelIngressKey-l","-l"]],selfDelPersonalAccess:[[114,0,1,"cmdoption-selfDelPersonalAccess-host","--host"],[114,0,1,"cmdoption-selfDelPersonalAccess-protocol","--protocol"]],selfForgetHostKey:[[68,0,1,"cmdoption-selfForgetHostKey-host","--host"],[68,0,1,"cmdoption-selfForgetHostKey-port","--port"]],selfGenerateEgressKey:[[69,0,1,"cmdoption-selfGenerateEgressKey-algo","--algo"],[69,0,1,"cmdoption-selfGenerateEgressKey-encrypted","--encrypted"],[69,0,1,"cmdoption-selfGenerateEgressKey-size","--size"]],selfGeneratePassword:[[70,0,1,"cmdoption-selfGeneratePassword-do-it","--do-it"],[70,0,1,"cmdoption-selfGeneratePassword-size","--size"]],selfGenerateProxyPassword:[[71,0,1,"cmdoption-selfGenerateProxyPassword-do-it","--do-it"]],selfListAccesses:[[72,0,1,"cmdoption-selfListAccesses-exclude","--exclude"],[72,0,1,"cmdoption-selfListAccesses-hide-groups","--hide-groups"],[72,0,1,"cmdoption-selfListAccesses-include","--include"],[72,0,1,"cmdoption-selfListAccesses-reverse-dns","--reverse-dns"]],selfListSessions:[[76,0,1,"cmdoption-selfListSessions-after","--after"],[76,0,1,"cmdoption-selfListSessions-allowed","--allowed"],[76,0,1,"cmdoption-selfListSessions-before","--before"],[76,0,1,"cmdoption-selfListSessions-denied","--denied"],[76,0,1,"cmdoption-selfListSessions-detailed","--detailed"],[76,0,1,"cmdoption-selfListSessions-host","--host"],[76,0,1,"cmdoption-selfListSessions-id","--id"],[76,0,1,"cmdoption-selfListSessions-limit","--limit"],[76,0,1,"cmdoption-selfListSessions-to-port","--to-port"],[76,0,1,"cmdoption-selfListSessions-type","--type"],[76,0,1,"cmdoption-selfListSessions-user","--user"],[76,0,1,"cmdoption-selfListSessions-via","--via"],[76,0,1,"cmdoption-selfListSessions-via-port","--via-port"]],selfMFASetupPassword:[[79,0,1,"cmdoption-selfMFASetupPassword-yes","--yes"]],selfMFASetupTOTP:[[80,0,1,"cmdoption-selfMFASetupTOTP-no-confirm","--no-confirm"]],selfPlaySession:[[81,0,1,"cmdoption-selfPlaySession-id","--id"]],whoHasAccessTo:[[115,0,1,"cmdoption-whoHasAccessTo-host","--host"],[115,0,1,"cmdoption-whoHasAccessTo-ignore-group","--ignore-group"],[115,0,1,"cmdoption-whoHasAccessTo-ignore-personal","--ignore-personal"],[115,0,1,"cmdoption-whoHasAccessTo-port","--port"],[115,0,1,"cmdoption-whoHasAccessTo-show-wildcards","--show-wildcards"],[115,0,1,"cmdoption-whoHasAccessTo-user","--user"]]},objnames:{"0":["std","cmdoption","program option"]},objtypes:{"0":"std:cmdoption"},terms:{"0":[0,2,4,5,6,7,9,10,11,12,14,15,16,18,19,21,23,27,29,47,52,59,82,84,113,115,121],"00":[11,12,19,91,119,121,123,124],"0000":15,"0010":16,"0021":16,"0022":23,"00m04":16,"00m05":16,"01":[11,12,91,121,123,124],"02":[11,12,19,124],"03":[11,12,15,19,22,91,123,124],"04":[19,20],"046":19,"05":[19,119,121],"06":[14,91],"0640":[2,4],"07":[11,14,91,119,121],"071":19,"074894":11,"08":[12,14,15,19,91,119,121,123],"09":[19,91,121,124],"0d":121,"0f":19,"0m":19,"0n":19,"0q":19,"0x5575da15aa78":11,"0x5575da36b690":11,"1":[0,2,4,5,6,7,9,10,11,12,14,15,17,18,19,21,22,23,47,99,117,119,121,123],"10":[0,12,14,15,19,20,123,124],"100":[0,16,17,19,121],"100000":0,"10006":11,"1001":19,"10057":11,"1024":5,"105":19,"1072497":11,"1072528":11,"11":[11,12,14,19,20,121],"111":0,"11264":19,"113":[0,27],"11860":19,"119":19,"12":[10,11,12,19,20,119,124],"120":[5,10,19],"123":11,"12345678":124,"127":[12,21,23,119],"13":[20,121,124],"1305":19,"13180":19,"1325900":11,"1325901":11,"14":[4,11,14],"1445":19,"15":[0,12,14,19,20,123],"153156":19,"1562861572":121,"1594384739":11,"16":[0,5,11,20,84,91,113,123],"1607524914":11,"1608561026":11,"1609427402":124,"168":0,"17":[10,11,12,91,124],"172":[11,12],"1789":19,"18":[19,20],"18720":11,"18721":11,"18802":11,"18803":11,"19":[0,15],"192":[0,2,10,19,29,59,121],"198":[19,121],"1d12h":27,"1d7h8m":[23,27,84,113],"1u":19,"1wfzo0umr15wzfis5fpy0m":124,"2":[0,2,4,5,10,11,12,15,17,18,19,23,29,59,117,119,121,123,124],"20":[0,15,19,20,84,113],"2000":0,"2018":19,"2019":121,"2020":[11,19,121,124],"2021":[22,123,124],"2022":91,"2023":[12,13,15,18,91,119],"20268":19,"203":[0,27],"2048":[0,45,59,69,105,124],"20518":11,"20519":11,"2070":11,"2091":19,"21":[11,19,29,91,123],"21mb":19,"22":[11,16,20,21,27,52,59,68,119,121,123,124,125],"222":[4,11],"2222":29,"2227":19,"2244":10,"224548":19,"23":11,"237":23,"24":[0,20,23,27,29,84,113],"2467":19,"2484":19,"249220":19,"25":[11,15,19],"250":17,"253440":19,"255":121,"256":[11,12,45,69,105,121],"26":[11,121],"2604":11,"2644":19,"27":[12,19,22,91],"27001":118,"271d":91,"28":[11,19,121],"29":[121,123,124],"2993de2bb014":124,"2d":124,"2dh2ojqj9bmgo5fuuupek":123,"2fa":[0,12,18],"2vo1ukyjjcq9exmcaweaaanomewweqykkwybbagcxaodawqdbqiembqgcisgaqqb":124,"2xd1agud":123,"3":[0,4,11,12,14,16,18,19,23,51,62,117,119,120,123,124],"30":[0,5,11,16,19],"31":[4,12,119],"3116603":11,"3116604":11,"31t15":124,"32":[5,59,84,113,121],"320":[15,16],"33":19,"3308206":11,"3308212":11,"33450":121,"3346532":19,"339483ff":2,"341":121,"35":12,"36":12,"3600":5,"37":121,"3708842":11,"3708843":11,"3709642":11,"3709643":11,"379":11,"38":[15,19,123],"382820":121,"384":[45,69,105],"386":21,"39":19,"391":11,"39696":11,"3am":20,"3dfb21e3857f562a603bd4f83f379ca7ecdf0537":19,"3f379ca7ecdf0537":19,"3noxi2xw0hwqu1":124,"4":[0,2,11,12,14,18,19,23,117,119,124],"40":19,"40000":0,"40610":121,"4088":19,"4096":[0,19,22,45,69,105,124],"41":[11,19],"41fdb9c7":2,"42":[0,19,59,121,123],"43":[11,15,121],"44":19,"440":19,"443":123,"444":59,"45":[59,121],"45140":[13,18,23],"4572":19,"46":[59,121],"48":124,"485":11,"48h":124,"49":91,"497020":121,"49999":0,"4d12h15m":[85,100],"4g":20,"4k":23,"4xuyr":121,"5":[11,16,17,18,23,123,124],"50":[15,19,23,91],"5000":16,"50000038":19,"50000039":19,"51":[19,91,121],"512":[5,19],"52":91,"521":[45,69,105,124],"537252":11,"537253":11,"55":15,"56":[11,119],"566":19,"56f321fb3e58":11,"57":121,"58":91,"59":91,"5d3cfdffa4480f26":19,"5h9f7csgi":124,"5zmznsyigdw7ft7co4tpld9d0pqvhdpk7f1zhifuxunfsewgtb3iqxldlgdacmzrri11v6q":124,"6":[0,18,23,123],"60":[0,12,121],"601a17b5e5ba":11,"605950307":15,"618577295":15,"65535":5,"65536":5,"664":14,"692":11,"7":[18,23],"705":19,"70qigxnkfv":124,"75":[19,91],"75ysw6nprdozjkjnwxg19lttvcmcy3eprfz":124,"77":11,"7wuu5uhszt3jvoz28rnij1p":124,"8":[0,5,11,14,18,19,23],"8192":[0,45,59,69,105],"8423":11,"8431":11,"8443":[5,123],"85tftxotxoiazy8upat2gggtsmcwo3shshjuyxrycf8e6jtjl":124,"86400":[0,6,63],"88":[12,121],"89":12,"8b0t6174kupl1itsyc0upndovuacgykpu8zo9rb2lco":124,"8k23zfjytn5nibk13ubxewshmuue1zcnfp0kdhqxbjyss":124,"8mb":19,"8pcvwcgkwcpvynbcmcdcm":124,"9":[18,19,23],"90":[0,2,12,91],"900":0,"905392":19,"91016":19,"94yetennwuy9ytg1dgadxgunq6zzjpjlddfxjuh0czw":12,"98d2f32b1a2d":11,"99":[20,121,123],"99994":11,"99998":11,"99999":0,"9_":119,"9a":124,"9f352fd4b85c":121,"9q":124,"9qsl1":123,"9sb2":123,"abstract":17,"boolean":[0,11,59,84,113],"break":[0,17,18,23,116],"byte":19,"case":[0,2,4,5,11,12,14,16,17,18,19,20,22,23,27,28,31,33,46,57,70,71,84,86,89,99,113,114,116,118,119,120,121,123,124,125],"catch":[0,47],"char":15,"default":[0,1,2,3,4,5,6,7,8,9,10,11,12,14,15,17,19,21,23,47,52,53,59,62,63,68,82,91,99,100,115,123],"do":[0,2,4,5,8,10,11,12,15,17,18,19,20,22,23,45,46,51,69,70,71,89,105,115,118,119,120,121,123,124],"export":[15,19,23,120],"final":12,"function":[0,2,15,16,17,18,20,23,24],"import":[0,11,14,17,23,120],"int":[0,2,4,5,6,9,10],"long":[2,4,5,11,12,17,19,22],"new":[0,5,10,11,12,15,16,17,19,20,22,23,24,30,49,58,99,107,117,119,120,123,124,127],"null":[16,59,99,119],"public":[0,2,4,11,12,14,19,20,21,23,31,49,53,58,84,85,91,99,107,108,113,115,120,121,124,127],"return":[0,11,15,16,19,23,52,119,121],"short":[0,2,4,11,20,121],"static":[20,23],"super":[0,11,121],"true":[0,3,5,8,11,12,14,17,19,23,84,100,113,115],"try":[11,12,17,19,21,23,27,46,70,89,115,121],"var":[11,19,23],"while":[0,10,11,17,19,23,102,116,124],A:[0,4,11,14,16,17,18,19,23,45,46,69,70,89,90,91,105,117,119,120,121,123,125],AND:12,AT:[119,121],And:[22,122],As:[2,4,11,12,15,16,19,22,23,91,112,119,120,123,124],At:120,BY:[119,121],Be:21,But:20,By:[0,11,23],For:[0,5,10,11,12,14,15,17,20,23,45,57,64,65,69,82,100,105,116,121,125],IF:[121,123],IN:0,IS:[10,121,123],IT:122,If:[0,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,28,31,32,33,35,45,47,52,54,56,57,59,66,67,72,82,86,92,93,99,100,108,114,119,120,121,123,124,125],In:[0,4,11,12,15,16,19,20,22,23,39,72,93,119,120,121,123,124,125],It:[0,4,11,15,17,19,20,21,22,23,118,119,120,122,123],Its:125,NO:0,NOT:[0,2,4,12,15,16,19,22,47,105,121,123],No:[18,23,100,118,123],Not:19,OF:19,OR:12,Of:[5,9,19,20,21,23,120,121,123],On:[0,11,17,19,22,23,120,124,127],One:[12,15,17,19],Or:[19,21,65],Such:[17,19],THAT:10,THE:19,That:[21,120],The:[0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,19,20,21,22,28,29,32,33,34,35,37,38,39,40,42,43,47,53,55,56,59,64,68,72,73,74,75,84,90,91,93,94,95,96,100,101,116,117,118,119,120,121,123,124,125,126],Their:[74,95],Then:[0,11,12,15,19,20,22,23,120,125,127],There:[11,16,17,19,20,62,120,124],These:[0,1,2,4,5,6,9,10,11,12,16,23,119,120,123],To:[4,5,11,12,15,17,19,20,22,23,27,31,60,64,65,82,84,113,120,121,123,124,125,127],Will:[0,11],With:123,__anon__:11,a00993ec6767:11,a0:16,a1:16,a2:16,a3:16,a4480f26:19,a46e51b5dce4:11,a5hrell8clv88jutjr2nih:124,aaa:19,aaaa:127,aaaab3nzac1yc2eaaaadaqabaaabaqcyamtxgt:124,aaaab:11,aaaac3nzac1lzdi1nte5aaaailny2nqtkstdxgcate6vhvm9fibud1rjcyq:121,abl:[0,2,4,12,14,19,20,23,32,34,37,38,39,40,42,43,44,59,65,82,85,90,106,113,118,119,120,123,125,127],abnorm:[11,14],abort:[11,15,19,23,29],about:[0,4,5,11,12,17,18,20,21,57,58,76,107,116,119,120,121,125,126],abov:[0,2,4,5,11,12,14,15,16,19,20,21,22,23,25,27,119,121,123,124,127],abruptli:11,absolut:20,ac777d06bec9:[12,23,119],ac:14,accept:[5,10,14,59,99,120,123,127],access:[0,1,12,14,15,17,18,19,20,21,22,23,27,28,32,34,36,46,47,53,54,57,58,64,65,70,71,73,82,89,91,94,107,108,116,118,119,122],accordingli:[0,19,23],accoun:93,account0:16,account0key1fil:16,account1:16,account2:16,account3:16,account:[5,15,16,17,18,21,23,25,28,36,47,48,49,51,58,59,65,71,82,90,101,105,107,112,118,119,120,121,122,123,125,127],account_mgmt:0,account_uid:11,accountaddpersonalaccess:[14,18,23,28,31,94,107,123,125],accountcr:[0,18,20,91,107,119,122],accountdelet:[16,18,91,107],accountdelpersonalaccess:[18,23,33,107],accountfreez:[18,107],accountgeneratepassword:[18,23,107],accountgrantcommand:[18,57,107,121],accountinfo:[16,18,107],accountlist:[18,107],accountlistaccess:[18,107],accountlistegresskei:[18,84,107],accountlistegresskeyss:84,accountlistingresskei:[18,107],accountlistpassword:[18,23,84,107],accountmaxinactivedai:[85,99],accountmfapolici:[12,99],accountmfaresetpassword:[18,107],accountmfaresettotp:[18,107],accountmodifi:[0,12,14,18,23,77,78,97,98,107],accountpiv:[0,18,107,124],accountrevokecommand:[18,107],accountsql:[11,23],accountsql_clos:23,accountunexpir:[18,107],accountunfreez:[18,107],accountunlock:[18,107],accumul:120,achiev:[12,17,116,120],acknowledg:20,acl:[1,19,20,22,23,30,84,113],acl_from_text:22,aclkeep:[0,11,14,18,39,43,49,57,91,120,123],acronym:58,across:23,act:17,action:[4,10,11,12,15,19,60,118,120,124],activ:[0,5,11,17,19,59,85,90,91,99,102],actor:14,actual:[9,11,15,16,17,19,20,27,28,29,31,33,46,57,70,71,84,86,89,113,114,118,119,120],ad:[0,5,11,12,16,19,23,27,53,64,65,73,82,84,94,100,113,119,120,121,123,124,125],adapt:1,add:[0,11,12,15,16,17,19,20,22,23,28,30,36,48,49,51,58,105,107,120,121,124,125],added_bi:124,addedbi:119,addedd:119,addit:[0,2,11,14,17,18,20,23,27,58,59,64,65,82,91,99,118,119,120,123,125],addition:[0,23,119],address:0,adetailedmessag:23,adjust:[0,19,20,22,23],admin:[0,11,16,17,18,20,21,22,23,57,59,91,120,121,122,123],admin_show_system_info:59,admin_user_ssh_key_path:15,adminaccount:11,administ:118,administr:[0,11,19,21,22,118,121],adminmainten:[18,26],adminsudo:[12,18,26],advanc:[11,12,18,20,23],advers:[19,22],advertis:[0,20],advis:[0,11,12,17,19,20,45,69,105,121,122],advisori:[14,18],aes128:5,aes256:5,affect:[14,99],aforement:14,after:[0,4,5,10,11,12,17,19,22,23,25,27,31,63,76,84,85,91,100,105,113,121,124],afterward:[0,50],again:[0,12,22,23,121,124],against:[0,15,20,27,28,31,33,84,86,113,114,123],ago:[12,91,121],agtccv:124,aim:116,aka:[11,12,59,121],alert:11,algo:[45,69,105],algorithm:[0,11,23,45,59,69,105,123,124],alia:[0,17,20,21,51,59,119,122],alias:0,aliv:[6,18,58],all:[0,2,3,4,6,7,8,9,10,11,13,14,15,16,17,18,19,20,21,22,23,28,31,32,33,34,39,47,53,54,58,59,64,91,99,100,105,115,116,118,119,120,121,122,123,124,125],allow:[0,11,12,14,23,24,27,28,31,33,47,59,66,76,84,85,86,99,113,114,115,118,120,121,124,125],allowedingresssshalgorithm:23,almost:[17,115],along:[0,4,12,21,38,53,66,121],alongsid:[23,27,31,84,113],alreadi:[0,1,4,12,18,19,20,21,23,31,100,119,120,122],alright:19,also:[0,2,4,5,11,12,14,15,16,17,18,19,20,21,22,23,27,29,31,33,34,53,66,77,78,84,85,100,113,115,118,119,120,121,124,125,127],alter:[1,22],altern:[4,17,22,29],although:22,altogeth:[2,3,4,6,7,8,9,10,99],alwai:[0,4,11,12,16,17,19,23,45,69,82,85,99,105,115,119,121,123,124],always_act:11,am:59,amaqk7t1oie0ook51wjx6j80gzf51pm00oplh4idvnnnxyn2kvknunwpocedd:124,amd64:21,among:[0,120],amount:[0,4,9,11,17,22,63,85,100,120,121],an:[0,4,5,11,12,14,15,16,17,18,19,20,22,23,29,30,36,44,47,48,49,58,71,85,90,92,105,107,108,113,114,118,119,120,121,122,123,124,125],anchor:119,ancient:[0,116],ani:[0,2,3,4,5,6,7,9,11,12,13,14,15,17,19,20,21,22,23,27,28,31,33,44,46,47,64,70,84,85,86,89,90,99,100,106,113,114,118,119,120,121,124,127],annoi:0,announc:117,anoth:[11,15,16,17,19,26,73,94,118,120],ansibl:[18,23,120],answer:[17,58,124],anybodi:[0,57,90],anyon:[0,14,120],anyth:[2,4,8,9,10,11,23,59,120,121,124],anywai:[11,17],anywher:[85,99],api:[12,16,18,71,116,123],app:[12,125],appart:[12,23],appear:[0,11,15],append:19,appli:[0,2,5,14,17,19,23,34,45,47,59,60,69,83,99,100,105,120,124],applic:[11,19],approach:120,apr11:19,apr:19,aqelbqadggebahcnp3k5kqabwymr9nuhkgy1dgcvhjulx2sayy2fueamuurcrrlw:124,ar:[0,1,4,5,9,10,11,12,14,15,16,18,20,23,24,27,28,31,33,55,57,59,64,66,67,71,73,74,75,84,85,86,88,94,95,96,100,108,113,114,117,118,119,120,121,123,124,125],arbitrari:15,architectur:[20,21],archiv:[2,7,19,123],argument:[15,22,121],aris:19,arm64:21,arm:21,armor:[19,23],aros:17,around:[11,17,23],arrai:[0,4,11,119],artefact:2,asc:22,ascii:0,ask:[0,11,12,14,19,21,22,23,79,87,99,122,124,127],asset:[12,29],assign:[14,105],associ:[11,58,107,119,127],assum:[23,121,126],assumpt:[0,122],attach:[6,12,19,118],attack:119,attempt:[0,9,11,12,17,35,56,62,72,93,127],attent:11,attest:[66,116,124],audit:[4,11,18,19,20,90,92,112],auditd:[17,120],auditor:[4,53,90,91,92,121],auth:[0,12,19,23,99,123,127],authent:[0,11,17,18,20,23,59,74,91,95,99,116,119,123,127],authenticationmethod:[12,19],author:[0,11,18,116,120,121,123,124],authorized_kei:[14,19,21,53,66,73,94,121],auto:[11,19,20,21,46,70,85,89,99,121],autocomplet:[12,121],autodetect:0,autogener:19,autologin:116,autom:[20,23,119,120,124],automat:[0,11,15,17,19,23,27,31,84,100,113],autonom:120,autonomi:[116,120],av:14,avail:[0,4,10,11,12,14,17,18,20,21,22,23,57,58,85,100,119,121,123],avoid:[0,5,11,12,19,20,23,119,124],awai:[46,70,71,89],awak:121,awar:[23,124],awk:[19,119],axvlifvmps02mvm8ndjc17x3lhsv1oi:124,b:[15,51,124,125],back:[2,12,15,16,17,19,23,50,100,102,124,127],background:[1,3],backup:[1,18,20,23],backupkei:22,backward:[0,23],bad:[0,11,17,123],balanc:19,bammifl1ymljbybqsvygum9vdcbdqsbtzxjpywwgmjyznzuxmcaxdte2mdmxndaw:124,banner:0,bare:[4,125],base64:19,base:[0,12,15,16,19,20,46,55,70,75,89,96,120],basedir:[0,15],bash:[15,16,19,118],basi:[0,14,20,118],basic:[0,3,17,18,19,22,58,116,120,123],bastion1:[0,12,19,119,123],bastion:[1,2,3,4,5,7,10,11,12,13,14,15,16,21,22,23,25,26,27,28,31,33,49,51,57,58,60,66,73,74,76,83,84,86,90,91,94,95,99,100,101,102,105,107,108,113,114,115,116,117,118,119,120,122,123,124,125,126],bastion_account:[52,123],bastion_com:11,bastion_conf:1,bastion_debian10_target:16,bastion_vers:11,bastionip:11,bastionm:59,bastionport:11,bastionsync:[10,19],bastiontest:[16,21],batch:[18,19,58],beast:[18,120],becaus:[0,2,11,17,20,23,99,115,118,120,121,124,125,127],becom:[99,120],been:[0,4,6,7,9,11,12,13,17,19,20,22,57,76,84,102,118,120,121,124,127],befor:[0,1,2,4,6,7,9,11,12,15,16,17,19,20,22,23,52,68,76,91,100,118,124,127],beforehand:23,beggin:0,begin:[121,124],behalf:11,behav:124,behavior:[0,1,5,6,12,13,14,23,99],behaviour:[0,23,99],behind:119,being:[0,4,6,10,11,12,17,19,20,21,23,29,84,90,113,125],below:[0,3,5,10,11,12,15,16,19,20,21,22,23,31,35,46,53,54,56,65,70,71,72,82,89,91,92,93,100,115,116,117,118,119,121,127],belt:118,best:19,better:[17,116,118],between:[0,5,11,15,16,17,18,19,45,47,59,69,84,105,113,116,118,119,125],bewar:[46,70,71,89,105],beyond:120,bfw6cvlajvss5dy3o6jwdmk:124,bgzccszaezmfftgwxq:124,big:[0,120],bikei:124,bin:[0,11,15,19,20,21,23,120,121],binari:[0,15,20,23],bind:5,bit:[17,22,59,120,127],bite:17,blame:[44,87,106],blank:11,blindli:[27,99,118],blob:12,block:[0,11,12,17,29,30,58,120],blog:[17,117,120],blue:57,bmzorlwba6l5ehwlhbh1o0u4g:23,bodi:[5,123],bofh:[59,121],bogu:23,bookworm:[20,23],bool:[3,5,8],boot:19,bot:0,both:[0,5,11,12,17,19,20,23,57,66,119,123,125],bother:17,box:[12,20,127],branch:15,brand:[20,120],breakag:23,briefli:125,broadli:0,broken:[0,11],brought:22,brows:127,bsd:[15,20,125],bssh:[0,12,23,51,119,121,123,124,125],bsshm:121,bug:[0,13,14,16,118],build:[0,15,21,23],built:[1,23],builtin:[17,18,124],bullsey:20,bunch:11,bundl:19,busi:[5,9,11,23],buster:20,button:23,bypass:[14,23,59,80,91,99],bzst1:123,bzvhsvux:123,c3rhdglvbia5ytccasiwdqyjkozihvcnaqebbqadggepadccaqocggebaliay3ez:124,c:[11,12,14,19,20,22,63,121],ca:[17,124],cach:0,call:[0,2,3,4,6,7,8,9,11,12,15,17,18,19,20,21,23,25,57,64,118,119,121,123,124],callabl:57,caller:[0,118],can:[0,3,4,5,10,11,12,14,15,16,18,19,20,21,22,23,27,28,31,33,35,41,44,47,50,53,54,56,57,60,64,65,66,67,72,73,76,82,84,85,86,90,91,92,93,94,95,99,100,102,105,106,112,113,114,115,118,119,120,121,123,124,125,127],cannot:[11,22,120],capabl:120,card:[121,124],care:20,carefulli:[17,18],carri:99,cast:11,cat:[19,23],catastroph:4,categori:[11,121],caus:[20,22],caution:67,cd:23,cento:23,central:[17,122],cert:5,certif:[5,17,19,66,124],certifi:[118,124],cet:19,cf:[23,27,84,113],chacha20:5,chage:0,challeng:[0,85],chanc:[17,19],chang:[0,4,9,10,11,12,17,19,20,23,68,91,99,100,119,124,125],channel:82,charact:[0,23,27,28,31,33,46,70,84,85,86,89,113,114,121],charg:18,chase:0,cheat:[45,69,105],cheatcod:0,check:[0,2,4,5,12,15,16,18,19,21,22,23,35,58,85,92,99,111,113,115,116,118,121,123,125],check_uid_gid_collis:19,checker:20,checkout:[15,20,23],checksum:19,chef:[23,120],chgrp:19,child:5,children:5,chmod:[14,19],choic:[5,17],choos:[12,14,19,20,45,69,105,127],chosen:20,chown:14,ci:20,cidr:[27,28,29,31,33,84,86,113,114],clariti:[12,57],classic:[5,12,23],clean:3,cleanup:[1,23],clear:[7,119,120],cli:126,click:127,client:[0,11,15,17,18,19,123],clipboard:19,clone:[15,20],close:[0,17,23,121,127],closest:31,clush:[18,58],cluster:[10,18,23,29,60,76,83],cmd:[25,52],cmdline:11,cmdlist:51,cmdtype:11,code:[0,12,15,16,17,18,19,22,23,52,99,118,119,120],collect:[9,19,23],collis:19,color:[58,119],colord:19,column:[11,121],com:[12,15,17,20,23],come:[11,16,22,120],comma:[52,108],command:[0,4,11,12,15,16,17,18,19,20,21,23,25,27,28,31,33,35,44,46,48,50,53,56,58,60,62,64,65,68,70,71,72,82,83,84,85,89,91,93,99,102,106,107,112,113,118,120,121,123,124,125],comment:[11,12,19,23,27,29,31,84,85,108,113,119],comment_clos:11,commit:[18,19],common:[4,11,18,125],commun:118,compact:119,compani:[0,18,116,120,124],companion:127,compar:12,compat:[0,19,23,66,123],compil:20,complementari:120,complet:[4,5,16,17,18,19,20,23,31,46,70,71,89,120,121,123],complianc:20,complic:[20,120],compon:[0,19,22,120],compos:[4,120],compress:[0,4,11,23],compromis:[17,22],comput:[0,121,123],concern:23,concurr:17,condit:14,condition:12,conduct:12,conf:[1,12,14,19,20,21,23,59,84,113,123],confid:12,config:[0,1,2,3,4,6,7,8,9,10,16,19,20,23,91],configd:12,configur:[0,2,3,4,6,7,8,9,10,11,14,15,17,18,21,22,49,58,66,85,100,102,107,118,120,123,124,125],confirm:[14,44,52,79,80,87,106],confus:17,congratul:121,connect:[0,5,9,10,11,12,14,15,16,17,18,21,23,27,28,31,33,47,52,59,62,76,84,85,86,91,99,100,107,113,114,115,116,118,119,120,122,123,124,125,127],consequ:91,conserv:118,consid:[0,6,9,17,20,23,35,47,54,56,72,92,93,120,124],consider:23,consist:[0,15,23],consol:[11,17,19,20],constantli:118,constitut:29,constraint:[45,69,105],construct:[11,16],consumpt:116,contain:[5,9,11,13,19,22,23,29,35,54,56,72,85,92,93,119,123],container:[17,21],content:[14,65],continu:[19,22,23],contrari:124,contrib:[15,23],contribut:18,control:[11,17,19,20,118],controlmast:99,controlpath:99,convers:0,convert:[0,11],cool:17,cool_languag:17,copi:[15,19,20,21,84,121,127],core:[12,18,117,120],corner:23,correct:[0,16,19],correctli:[0,11,12,16,17,19,23,121,123],correl:[11,23],correspond:[0,11,19,22,23,55,75,96,120,123,127],could:[17,22,23,118,120],couldn:[11,23,121],count:63,counter:[0,91],counterpart:[74,95],coupl:11,cours:[0,5,9,17,19,20,21,23,115,120,121,123],cover:[19,20,84,113,120],cp:[15,120],cpu:[0,19],crash:[11,23],creat:[0,2,4,9,11,14,15,16,17,18,22,23,49,58,91,107,116,119,120,121,122,123,127],created_bi:11,creation:[0,11,20,47],creation_tim:11,creation_timestamp:11,credenti:[2,12,18,22,58,123,127],critic:0,cron:[2,3,4,6,7,8,9,11,19,20,23],crond:[2,6,7],cronjob:0,crowd:122,cryptographi:23,cryptsetup:20,ctrl:[19,121],cumbersom:12,cumul:12,curl:123,current:[0,4,11,12,15,19,23,30,58,123,124,125],curv:[23,127],custom:[0,21,23],cut:[17,21,119],cv25519:19,cve:[18,23],cvss:[14,23],cww6vvsfydwn01kc6ylrwm5fin:124,cycl:11,d1:124,d2bdf9b5:19,d5b1thkkgstsfzvzoopwijj86ciwpcyunfej:124,d5blcrakrt9p8mst7bhwu14ghjddhhdy4rmnxape93oxbnqijqt34ozvtklb0qoor:124,d:[0,5,11,12,15,16,18,19,20,21,22,23,99,119],da97efd1:2,dac:118,daemon:[0,5,11,12,17,19,20,22,23,123],dai:[0,2,4,9,12,17,23,85,91,99,123,124],daili:[19,20],danger:0,dangl:3,dark:20,dash:25,data:[4,10,11,17,19,22,23,27,53,55,62,91,119,123],databas:[11,17,18,23,29,118],date:[11,15,19,20,23],datetim:[11,124],dd:[22,76],de:17,deactiv:[85,100],deal:120,dear:121,deb:[20,23],debian10:21,debian11:20,debian12:[12,15],debian:[15,20,23],debug:[4,11],dec:11,decentr:122,decid:[12,17,20,124],decis:[0,119],declar:[19,107,115,118,120,125],decor:0,decoupl:116,decreas:23,decrypt:[4,19],dedic:119,dedmrmsbptsrc3t7rwoqca80iq1jpvdm5gw:124,deem:[0,23],deepli:17,defin:[0,2,4,12,16,17,99,100],del:[11,23],delai:[5,10],deleg:[18,39,116,117,120],delet:[0,2,4,7,11,16,17,19,22,41,49,67,107,120],deliveri:17,deni:[0,19,76,85,118,121,123],depend:[0,5,11,12,15,19,20,63,82,116,119,120,121,123],deploi:[1,22,23,46,70,89],deposit:[66,85,108],deprec:23,depth:19,describ:[11,120],descript:[0,11,100],design:[0,11,17,23],desir:23,desk:[19,20],desktop:17,dest:[64,65],destin:[0,9,11],detail:[0,11,18,22,23,76,119,121,124],detain:[74,95],detect:[10,11,17,20,23],determin:0,dev:[20,59,99],develop:[15,20],devenv:15,devic:[5,17,23,46,55,70,71,75,89,96,116,120,123,124],devop:18,dgvzdgf0aw9umiibijanbgkqhkig9w0baqefaaocaq8amiibcgkcaqeawdhp3yui:124,dialect:17,dialog:127,did:[23,119,121],didn:[0,12,23,121],differ:[0,9,11,12,15,18,19,22,23,45,53,57,69,105,116,125],dir:4,direct:[19,108,123,125],directli:[0,2,4,6,7,9,10,11,12,16,17,20,21,23,66,67,121],directori:[0,4,5,7,9,10,11,15,19,20,23,64],dirti:18,disabl:[0,3,4,5,9,11,12,14,20,23,47,59,85,91,99,100,115,119,124],disallow:24,disappear:17,disconnect:[0,12,121,123],discourag:[0,15,17,20,22,23],discrep:[19,22],discret:12,discretionari:118,disengag:0,disk:[4,17],displai:[0,11,12,17,23,53,57,58,76,88,94,107,127],dist:[19,23],distant:4,distinct:[17,119,123,125],distribut:23,distro:[5,12,19,20,22,82],dive:121,dizzi:117,dk:121,dn:[0,18,35,56,72,93],dnssec:19,doabl:120,doc:[1,15,19,125],docker:[16,18],docker_build_and_run_test:15,dockerfil:[17,21],documen:12,document:[0,15,19,20,22,23,99,116,119,121,124,125,126],doe:[0,14,16,18,19,23,99,100,115],doesn:[0,4,11,12,16,17,19,20,23,46,70,77,78,84,89,97,98,113,118,119,120,121,123],don:[0,2,4,5,6,7,8,9,10,11,14,15,17,19,20,21,22,23,25,27,29,46,52,54,55,57,59,61,66,70,72,75,79,85,87,89,92,93,96,99,100,105,115,118,124,125,127],done:[0,11,12,17,19,20,22,23,35,51,56,61,65,72,82,84,93,118,119,121,123,127],doubl:[23,25,66,108],down:[17,19,22],download:[14,20,23,27,28,31,33,64,65,82,84,86,113,114,116,125],dqaxohbima0gcsqgsib3dqebcwuamcsxktanbgnv:124,dr:17,draw:0,drive:17,drop:[0,5,19,23,127],drugngsk:123,dry:[15,19,29],dss:118,dtm5hksykt18bnvfft:123,due:[11,17,20,123,125],dummi:15,dump:[53,91],duo:0,durat:[11,23,27,31,47,84,85,100,113,121,124],dure:[4,11,12,16,20,23,121],dynam:17,e192fce7553a:11,e9e4baf6873b:11,e9qkc7d6:123,e:[0,4,10,11,12,14,17,19,20,47,53,84,90,99,108,113,115,119,121,123],each:[0,4,10,11,12,15,16,20,21,52,76,105,119,120,123,124],earli:[11,17],eas:15,easi:[0,92,116,118,121],easier:[0,11,17,22,119],easili:[23,124],ecdh:5,ecdsa:[0,5,23,45,59,69,105,121,124],echo:[19,23,51],ed25519:[0,11,12,15,19,45,59,69,105,121,124,127],eddsa:127,edg:18,edit:[4,19],ee4c91000b75:11,effect:[0,15,19,20,22,48,99,100,120,123,124],effici:120,egress:[11,14,17,19,21,28,31,33,45,49,53,58,59,84,91,99,105,107,116,120,121],egress_ssh_key_algorithm:11,egress_ssh_key_encrypt:11,egress_ssh_key_s:11,ehjupeauhq7n0tjzmf1x7kelx9fzzm9heuxujvzv7xwiuga4zm05:124,either:[0,10,11,12,14,16,17,20,23,27,28,29,31,33,45,57,69,83,84,86,105,113,114,118,119,120,122,123,124,125],elev:12,elig:[4,28],ellipt:23,els:[0,9,10,17,20,49,90,120],email:19,embed:123,emit:[11,23,124],emoticon:0,emphas:119,empti:[0,1,2,3,4,5,6,7,8,10,11,23],enabl:[0,4,11,12,14,17,18,20,23,59,82,91,99,100,118,119,123,124],enableaccountaccesslog:[11,23],enableaccountsqllog:11,enableglobalaccesslog:[11,23],enableglobalsqllog:[11,23],enablesyslog:19,enact:120,enclos:119,encod:123,encount:[11,119],encourag:[19,23],encr:19,encrypt:[1,11,18,22,23,45,69,105],encrypt_and_move_delay_dai:4,encrypt_and_move_user_logs_delay_dai:23,encrypt_and_move_user_sqlites_delay_dai:23,end:[2,11,12,19,20,22,23,120,121,124,127],endless:17,enforc:[0,14,15,23,47,91,99,100,116,118,120,124],engin:16,enhanc:0,enough:[0,4,5,14,19,23,91,125],enrol:80,ensur:[0,2,4,5,9,10,11,12,15,16,17,20,23,46,70,84,89,113,116,118,123,124,127],enter:[11,12,19,20,21,105,121,123,124,127],entir:[12,18,23,99,119],entri:[16,18,20],entropi:19,env:15,environ:[0,1,12,14,17,18,19,20,45,69,105,118,125],envvar:0,eo:19,eol:23,epvf1cvvzoeqf:23,equival:[16,17,121,123],era:117,eras:19,err:[11,15,119],err_member_cannot_be_guest:119,error:[0,11,12,15,16,20,22,23,29,59,82,119,121],error_cod:16,escal:0,escap:[0,27,28,31,33,84,86,113,114,118],escrow:11,especi:[11,19,121],essenc:12,establish:[0,11,14,127],etc:[0,4,5,11,12,14,15,17,18,19,20,21,22,23,59,84,99,113],etzzxxbvu9kibszyhvb:124,even:[0,6,10,11,12,15,17,18,19,20,22,23,54,58,85,99,118,119,120,121,124,125],event:[0,11,23,124],ever:[17,99],everi:[0,11,12,15,91,118],everybodi:[0,17,120],everyth:[2,11,19,53,91,121],everywher:[0,17,19],evolv:19,exact:[11,16],exactli:[0,12,16,47,121],exampl:[0,2,4,5,10,11,12,15,17,18,19,20,22,23,25,27,29,51,58,65,82,107,120,121,123,124,125],except:[0,2,11,16,53,91,124],exchang:62,exclud:[4,12,14,19,35,53,54,56,72,91,92,93],exclus:[0,118],excus:[59,121],exec:21,execut:[0,11,12,16,23,118],execv:11,exist:[0,4,11,12,14,16,18,19,20,28,31,33,46,70,89,92,111,119],exit:[0,5,12,16,52,58,63,119],expand:[0,11,107],expect:[0,11,12,14,15,16,17,20,23,50,66,108,127],expir:[0,3,8,12,23,27,31,59,84,85,91,99,107,113,120,124],expiri:119,explain:[0,12,16,18,19,117,122,125],explicit:[12,23,119],explicitli:[0,14,23,59,99],expos:119,express:0,extend:118,extens:[19,116],extent:0,extern:[0,2,15,19,116],extra:[53,91],extract:[120,124],extrem:[0,120],ey:11,ezb1supteecng7qdr6qvkbxov586fx:124,f0:19,f25fe71c6635:11,f2:[21,119],f4cca44a848:121,f50bffc49143c821:22,f9:124,f:[0,11,16,17,19,21,67],fa:12,facil:[0,2,3,4,6,7,8,9,10,23],fact:[0,22,115,119,123],facto:17,factor:[14,18,20,59,91],fail:[0,15,16,22,23,52,82],faillock:0,failur:[0,4,52],fall:[12,19],fallback:[19,20,46,70,89,123],fals:[0,5,11,17,23,59],falsi:0,familiar:0,fanci:17,faq:[18,20,21],fast:[11,17],faster:[23,92,121],favorit:20,fb00e1957b22:121,fd:19,featur:[0,5,11,12,14,15,16,18,20,23,62,121,124],fed:[29,58],feed:[12,127],feel:14,fetch:[0,21,22,23],few:[0,7,11,12,15,16,23,58,120,121,124,126],ffee33abd1ba:11,fido2:[15,23],field1:[11,16],field2:[11,16],field:[11,16,19,23,119],fieldx:16,fifth:18,file:[0,2,3,5,6,7,8,9,10,12,14,15,16,18,20,21,22,27,51,53,58,68,73,94,116,121,125,127],filenam:[0,11,15],filer:[4,11],filesystem:[2,19,20,22,118,124],fill:[11,19],filter:[11,16],find:[11,13,16,17,23,64,65,81,82,124],fine:[0,17,20,23],fingerprint:[11,23,27,67,84,113,121,124],fire:12,firewal:[0,59],firmwar:124,first:[0,4,11,12,17,18,19,21,22,23,53,120,122,125,127],fit:[0,12,17,20,22,64,121],fix:[0,11,14,16,19,23],fjus6dgh1wdkpy4pdcvkmqrpeetb42bntsziwjygi1:123,flag:[0,12,19],flash:19,flexibl:[120,124],flow:[0,23],fly:0,fml0y7z4vgdo:124,focus:[12,18,116],fohv:124,folder:[0,1,2,15,16,19,21,23,65],follow:[0,10,11,12,14,15,16,19,20,21,22,23,29,59,65,82,91,119,121,123,124,125],foo:11,footprint:17,forbid:19,forbidden:59,forc:[0,12,14,15,19,23,27,59,66,84,113,116,121,123,124],force_kei:11,forcefulli:10,forcekei:119,forcepassword:119,foreground:16,forese:23,forev:0,forg:20,forget:[0,2,4,6,7,9,20,21,23,25,58,59,100,124,127],forgot:124,forgotten:[12,17],fork:14,form:[0,23,99],format:[0,2,4,5,18,22,23,29,59,66,84,108,113,123,124],forth:15,fortun:59,forward:[5,17,123],found:[4,11,12,14,15,16,19,20,21,23,100],fourth:18,fp:67,fpr:19,fr5lspymhz:124,frame:11,freebsd:20,freez:107,fri:[91,121],friendli:0,from:[0,2,3,4,6,7,8,9,10,11,12,14,15,16,17,18,19,20,23,25,27,30,31,36,41,49,58,59,66,73,76,84,85,94,100,107,108,113,116,118,119,120,121,123,124,125],front:[0,116],frozen:[88,91,107],fslist:19,full:[0,5,11,15,22,23,62],fulli:[11,17],functionali:12,further:[11,19],futur:[0,23,28,31,32,33,34,53,91,124,125],fx:124,g0fo:123,g:[0,10,11,12,19,84,90,113,119,123],gain:[0,73,94],garbag:[9,23],gatekeep:[0,11,14,18,39,43,49,57,91,120],gather:[11,53,91,92],gb:17,gcm:5,gen:19,gener:[0,11,12,15,18,20,45,49,58,65,69,82,105,107,119,120,123,124,127],genesi:117,geoclu:19,get:[0,1,4,5,9,11,15,17,18,19,21,22,23,41,59,67,82,84,90,101,118,120,121,123,124],gib:5,gid:[11,121],gigabyt:11,git:[18,20,23],github:[0,12,14,15,17,19,20],give:[0,11,17,19,20,23,32,68,112,119,120,125,127],given:[0,5,9,11,12,14,16,19,23,27,28,29,31,33,35,54,56,72,84,92,107,113,119,120,121,123],glob:[23,27,28,31,33,84,86,113,114],global:[4,11,14,17,18,19,23,47,85,99,100,122],globalsql:[11,23],globalsql_clos:23,gnat:19,gnupg:[19,23],go:[0,1,12,17,19,23,50,100,122,124],goal:125,goe:19,gone:120,good:[0,4,12,15,16,17,18,19,20,21,22,23,45,69,105,120,121,123],googl:[0,19,20],got:[11,18,19,23,120],govern:[1,6,9],gpg1:23,gpg:[2,4,17,18,23],grace:[1,18,100],grain:[0,20,23],grant:[0,14,17,19,20,36,44,57,64,65,82,107,112,118,119,120,121,123,125],great:[20,22],green:57,greet:21,grep:[19,119],greppabl:16,group:[0,2,3,17,18,20,23,32,34,51,57,58,59,64,65,72,82,90,91,93,99,107,115,116,118,119,121,122,125],groupaddaclkeep:[18,49],groupaddgatekeep:[18,49],groupaddguestaccess:[18,23,32,33,36],groupaddmemb:[18,28,31,36,51,125],groupaddown:[18,48,49],groupaddserv:[12,18,23,30,64,65,82,123,125],groupcreat:[18,91,107],groupdelaclkeep:[18,49],groupdelegresskei:[18,49],groupdelet:[18,44,91,107],groupdelgatekeep:[18,49],groupdelguestaccess:[18,23,31,36],groupdelmemb:[18,33,36],groupdelown:[18,48,49],groupdelserv:[18,23,30],groupdestroi:[18,49,106],groupgenerateegresskei:[18,49],groupgeneratepassword:[18,23,49,123],groupinfo:[12,18,27,41,58],grouplist:[18,58],grouplistguestaccess:[18,33,34,36],grouplistpassword:[18,23,27,58,123],grouplistserv:[12,18,28,31,53,58,119],groupmodifi:[12,14,18,49],groupsetserv:[18,30],grouptransmitownership:[18,49],grow:[11,23],growth:5,grp1:27,grp2:[27,91],grp4:51,gshadow:17,gsqkawcebgiealeg1jaqbgorbgeeaylecgmibaidatapbgorbgeeaylecgmjbaeb:124,gthreepw:11,guarante:[16,22,23,119],guess:[120,127],guest:[1,11,23,31,33,34,36,38,42,47,120],gui:[120,125,126],guid:20,guidanc:124,guidelin:[20,65,82],guybrush:12,gvf:19,gwvbcrp3ymbsw:124,gygxhes2nmzn37rll6vvpz4exm29urqu3hajyo0ha:124,gyxmyjao:123,gz:[2,19,20,22],gzip:19,h:[0,11,14],ha:[0,3,7,9,10,11,12,13,15,17,19,20,22,23,48,57,68,84,91,93,115,118,119,120,121,123,124,126,127],hack:17,hacker:20,had:[34,120,124],halt:[11,118],hand:[5,12,17,18,22,125],handi:[21,120],handl:[0,1,2,4,7,11,17,19,20,23,99,116,120,124],happen:[3,4,11,17,19,20,23,60,76,83,120,123,124,125],hard:[5,17,127],hardcod:[0,118],harden:[17,18,20],hardenedbsd:20,harder:120,hardwar:[0,15,18,20,66,100,123,124],harm:23,hash:[20,23,27,58,84,107,113,119,123],have:[0,2,3,4,6,9,10,11,12,13,14,15,16,17,19,20,21,22,31,39,47,53,54,57,58,59,60,64,65,76,82,83,105,107,112,118,119,120,121,122,123,124,125,126,127],haven:102,he:0,head:[20,21],header:[5,19,123],heavili:12,help2:16,help:[0,11,12,15,16,18,19,20,21,22,23,25,58,84,113,121,122],helpdesk:124,helper:[11,19,20,23,65,82,118],henc:[0,3,11,12,17,19,20,22,23,118,119,120,124,125],here:[0,10,11,12,13,16,17,18,19,20,23,59,119,120,121,122,124],herebi:12,heterogen:17,hh:76,hi:[0,11,31],hide:[17,72,93],hierarchi:[20,22],high:[9,10,11,18,22,123,124],higher:[0,4,47],highest:120,highli:17,highlight:[0,57],highwai:20,hint:[11,121],hit:[23,127],hmac:23,holder:[121,124],hole:120,home:[0,2,4,5,7,9,11,15,17,18,19,22,23,100,120,121,124],homedir:1,honor:14,hood:0,hook:[17,18],host1:29,host:[0,2,11,12,17,19,20,21,23,27,28,29,31,33,52,58,62,64,65,76,82,84,86,99,113,114,115,121,123,125,127],host_bast:11,host_from:11,host_to:11,hostfrom:11,hostkei:19,hostkey_chang:11,hostlist:52,hostnam:[0,11,19,29,35,50,52,56,72,93],hostto:11,hour:[0,23,124],how:[0,2,4,10,16,18,19,22,65,82,100,120,121,124,125],howev:[0,1,11,12,17,23,27,31,33,66,68,84,106,113,124,125],howto:126,hqlhcx9tdgj5zhhvd:123,html:12,http:[0,1,11,12,15,17,18,20,23,58,116,119],http_proxy_port_or_zero:15,human:[0,11,12,92,100,119],hundr:123,hup:11,hypervisor:20,hzusxrx9ghm4ma0huso9f0ubiso:123,i:[0,2,4,10,11,12,14,16,18,19,20,21,47,51,53,58,59,84,99,108,113,115,120,121],icmp:63,icon:18,id:[2,4,11,14,22,41,67,76,81,121],id_backup:2,id_ed25519_agroup:11,id_ed25519_backup:4,id_master2slav:[10,19],id_rsa4096_priv:11,idea:[0,4,15,17,19,119,120,123],ident:0,identifi:121,idl:[0,5,17,19,47,59,91,99,121],idlekilltimeout:[17,47,99],idlelocktimeout:[17,47,99],ignor:[0,4,5,10,11,19,46,70,71,89,99,115,119],ijo9mqvvso6hh9kvpxguww9blpqnpchswbhsakb:124,imag:[15,21],immedi:[11,14,18,27,28,31,33,84,86,100,113,114,118],immun:[23,91,99],immut:[11,85,118],immutable_kei:11,impact:[9,13,23,123],imperson:[0,11,26,120],implement:[12,23,119,124],impli:[0,12,16,23],implic:17,implicit:[0,11,23,120],implicitli:[0,23],imposs:11,impract:120,impress:17,improperli:17,inact:[0,12,83,85,91,92,99,107,121],inc:11,includ:[0,5,11,12,14,17,18,19,20,22,23,35,53,54,56,72,91,92,93,119,120,121,123,124],incom:[0,120],inde:[7,19],independ:19,index:18,indic:[0,11,16,19,23,57],individu:[120,124],infinit:63,info:[0,12,16,18,21,25,47,51,53,58,91,92,110,121,123,124],inform:[0,4,10,11,15,17,18,20,21,23,58,64,65,76,82,92,107,112,119,121,123,124],infrastructur:[0,17,18,19,20,23,119,120,121],ingress:[11,12,17,19,23,58,59,85,91,99,107,116,123,124],ingressrequirepiv:[100,124],inherit:0,init:[5,20],initi:[12,23],inon:19,inotifi:0,input:[0,12,17,22,29,59,118,127],insert:[11,23],insid:[15,19],inspect:19,inspir:120,instal:[0,5,10,11,12,15,23,59,85,113,115,120,121,122,125],instanc:[15,19,20,22,23,58,60,76,83],instantli:120,instead:[0,4,10,11,12,16,17,19,20,23,28,31,32,33,47,119,121,123],instruct:[0,12,18,19],integ:[0,5,84,113],integr:[16,18,19,23,120],intend:119,intens:[0,23],interact:[0,11,15,17,18,19,21,23,59,61,66,67,85,88,105,108,116,119,121,127],interactivemodebydefault:23,interactivemodeproactivemfaen:12,interactivemodeproactivemfaexpir:12,interest:[11,12],interfac:11,interfer:118,intern:[0,12,17,20],interpret:0,interrupt:11,intersect:125,intertwin:17,introduc:23,introduct:[18,116],intrus:17,invalid:[16,22],invoc:0,invok:119,involv:119,io:[0,12],ip1:[66,108,124],ip2:[66,108,124],ip:[0,9,10,11,14,15,19,23,29,30,31,33,50,52,58,59,62,76,84,86,108,113,114,119,120,121,125,127],ip_bast:11,ip_from:11,ip_to:11,ipbt:11,ipfrom:11,iptabl:20,ipto:11,irc:19,irrelev:17,ish:53,iso:118,isol:119,issu:[11,14,17],item:[0,5,19,120],its:[0,4,5,10,11,12,14,17,19,20,22,23,47,66,76,100,115,118,119,123,124],itself:[0,17,18,19,22,99,118,120,121,123,127],j2t:124,j:17,jargon:0,jd:19,jdoe12:91,jdoe:[23,91,124],jit:[0,18,23],job:[19,20,23,65,82,123],joe:11,john:19,johndo:[0,12,84,113,119,121],joke:17,jolt:121,jq:[16,119],json:[12,18,23,53,59,84,91,92,113,118],json_end:119,json_output:119,json_start:119,jump:12,jumphost:17,jun:123,just:[0,10,11,12,16,17,19,20,22,23,27,29,62,64,65,82,99,115,120,121,122,123,124,127],keep:[0,2,5,11,15,17,19,20,23,121,123],kei:[0,1,4,5,8,10,11,12,14,15,17,18,20,21,23,27,28,31,33,46,49,53,55,58,59,70,75,84,85,89,91,96,99,105,107,108,113,115,116,118,119,120,121,123,125,127],kept:[6,11,23,100,123],kernel:20,kerneloop:19,kernoop:19,kex:23,kexalgorithm:23,key1:4,key2:4,key3:4,keyagroup:11,keyboard:[0,12,17,19,59],keyfil:19,keygen:[19,124],keyid:4,keykeep:11,keylin:121,keyr:[2,4,22,23],keysomegroup:11,keystrok:[0,11],kf0xsjial4pkgvxeaqtp0:124,khm3:124,kill:[0,5,19,23,47,59],kind:17,kl5g8tr:124,knob:23,know:[0,5,12,17,19,20,22,23,46,70,71,89,115,119,122],known:[0,11,17,20,23,58,118,121,123,124],known_host:68,ko:119,ko_access_deni:119,kywypciiu7cmtlprykl5salwmucaz8dzpk5flppeqmxgqnrosse67ixiv3bnypa1:124,l3zbwzfh9mtpo4wlx29jd8ltm5sklfejtrz:23,l:[11,14,67],la:[0,66],lack:20,languag:17,larg:[11,120],last:[0,3,4,12,23,91,120,121],lastlog:19,later:[0,19,20,127],latest:[20,22,23],launch:[0,5,11,15,19,20,25,58,60,83],launch_tests_on_inst:15,layer:[4,17,20],ldap:0,lead:11,leak:0,leap:[20,23],learn:[65,82,121],least:[0,4,5,11,12,17,19,23,91,120,125],leav:[0,5,12,120,123,127],lechuck:[11,124],left:[0,2,4,12,20,21,121],legaci:116,legend:17,legit:[68,124],length:[19,23,123],less:[0,120],let:[11,12,16,21,119,121],level:[4,17,20,23,57,118,120,121,124],leverag:[17,118,119],li:120,lib:[11,15,19,20],libexec:19,librari:[5,11,17,123],lift:125,like:[0,12,15,17,18,19,23,58,118,119,120,123,127],limit:[4,5,20,47,76,84,113,120],line:[0,11,12,15,16,19,23,29,51,119,121,124],linger:1,link:[11,117,124],lint:15,linux:[15,19,20,21,23,125],list:[11,12,15,17,19,22,23,30,33,36,37,38,39,40,42,43,47,52,53,58,84,90,101,107,108,119,121,122,123],listen:[5,123],littl:120,live:[0,16,17,20],ll:[0,2,3,4,5,6,7,8,9,10,11,12,15,16,17,19,20,22,23,31,46,57,64,65,66,67,70,71,77,78,82,85,89,90,105,108,115,120,121,123,124,127],llmb9giamjnffr6gj7gzonik2jdltecb:123,lmbm2xikb1bsw3skjhomv30pq:124,lngt:124,load:[12,19,121,127],local6:[2,3,4,6,7,8,9,10,23],local7:0,local:[0,2,4,11,15,17,19,23,64,116,118,125],localfil:65,locat:[4,9,12,15,19,20,22,65,82,127],lock:[0,11,18,19,24,47,58,59,83,107,124],log:[5,15,17,18,29,116,118,121,123,124],log_request_respons:23,log_request_response_max_s:23,logarithm:11,logfil:19,logic:[12,17,118,119,120],login:[0,12,19,23,24,65,82,99,121,127],logkeep:[0,4,11,23],logrot:[2,4,6,7,9],longer:[0,3,6,12,23,34,40,42,43,120],look:[11,12,16,17,19,35,68,119,121,127],loopback:19,loos:17,lose:[20,124],loss:4,lot:[0,9,11,15,17,19,20,23,51,120],low:[0,4,5,17],lower:[0,47],lt:[20,23],lucki:0,luks1:20,luks2:20,luksformat:20,m2m:[12,119],m:[0,11,15,58,59],ma0gcsqgsib3dqebcwuaa4ibaqaq9o6h02krvsmbysz23r6cntn:124,machin:[0,11,15,18,19,21,22,27,28,58,72,73,93,94,115,118,120,121,123,125],magic:[0,120],mai:[0,4,7,9,11,12,14,15,16,17,19,20,22,23,29,34,45,66,69,105,119,120,121,124],mail:17,main:[16,18,19,20,22,50,116,118,120,124,125],mainli:[0,12,111,112,116,118],mainten:26,make:[0,17,19,20,23,92,99,121,122,123,124],man:[0,68,99,116],manag:[0,4,17,18,19,20,23,26,37,38,39,40,42,43,121,122,124],mandat:11,mandatori:[1,2,4,10,12,20,23,123,124],mani:[0,17,120],manner:22,manual:[12,18,19,23,58,64,83,120,123],map:[118,120],mar:19,margin:19,mark:19,mask:23,master:[0,4,12,59,121],match:[0,11,12,15,16,19,22,27,28,31,33,35,54,56,72,84,86,92,93,113,114,115,119],matter:[5,12,17],max:[0,63,85,99],maximum:[0,5,10,20,23,91],mayb:23,md5crypt:123,mdawmfoydziwntiwnde3mdawmdawwjahmr8whqydvqqddbzzdwjpy28guelwief0:124,me:[12,59],mean:[0,2,3,4,6,7,8,9,10,11,18,20,21,23,59,82,99,115,120,123,125],meaning:[12,100],meant:[0,45,69,105],measur:[0,2,4,91,116,123],mechan:[0,17,18,23,46,70,89,119,124],megabyt:5,mem:19,member:[11,12,14,17,28,33,36,38,42,47,53,91,115,122,125],membership:20,memori:17,menu:[20,21,121],mere:17,merg:17,messag:[0,12,18,23,24],meta:58,metadata:[11,58,107,124],method:[12,15,19,22,120,123],mfa:[0,15,18,20,23,47,59,91,99],mfa_requir:12,mfapasswordinactivedai:12,mfapasswordmaxdai:12,mfapasswordmindai:12,mfapasswordwarndai:12,mflejiwskzbkyu5g2gg042tulnnckplmmnpnijgnd8rpnlddu:124,mfoydziwntiwnde3mdawmdawwjalmsmwiqydvqqddbpzdwjps2v5ifbjvibbdhrl:124,microsecond:0,microsoft:125,middl:[68,116],might:[0,4,11,12,13,15,16,17,18,19,20,22,23,27,28,31,33,66,84,86,113,114,116,119,120,125],miic5jccac6gawibagijakt:124,miididccagigawibagiqaajpkefbm:124,million:123,millisecond:[11,23,123],mimic:120,min:0,minimum:[0,4,6,15],minor:[11,20],minut:[12,15,17],misbehav:11,misconfigur:[11,23],mismatch:19,miss:[0,2,3,4,6,7,8,9,10,11,20,23],mistak:[22,120],mitig:23,mkdir:20,mkhash:[20,23],mm:[22,76],mobil:0,mode:[0,11,15,17,19,21,23,26,59,88,92,118,119,120,121,127],model:[18,19,120],modern:20,modif:[0,4,11,15,19,59,85],modifi:[0,4,5,11,12,14,15,16,17,20,23,29,49,107,121,124],modul:[0,5,15,16,17,20,23,118],modular:118,mon:[11,123],monitor:[23,50,123],monkei:11,month:[4,11,23],moot:20,more:[0,4,5,10,11,12,14,16,17,19,20,21,23,59,64,65,76,82,90,92,119,121,122,123,124,125,126],moreov:120,mosh:[0,59,116,121],mosh_server_network_tmout:0,mosh_server_signal_tmout:0,most:[1,16,17,22,46,47,70,71,89,117,118,119,120,123],mostli:[11,126],mount:[4,15,19,22],mountpoint:19,mous:127,move:[4,23,127],mr8whqydvqqddbzzdwjpy28guelwief0dgvzdgf0aw9umcaxdte2mdmxndawmdaw:124,msg:11,msgtype:11,msxkgtpdpvhveqnmhh4qyyryixwwatbdcgoqd:124,mtr:[18,58],much:[0,3,4,19,23,100],multi:[4,18,59,91,123],multipl:[12,15,35,54,56,72,92,93,123],multiplex:99,must:[0,2,4,6,9,12,14,16,22,23,27,28,31,33,59,84,85,86,91,113,114,118,123,125],my:[0,18,59],mybastion4:19,mybranch:15,mygroup2:53,mygroup:[119,125],myhostnam:11,mynam:[19,121],n:[0,14,15,19,51],name:[0,4,11,12,15,16,17,19,20,21,22,23,25,27,28,31,33,35,41,44,45,47,54,56,57,72,84,85,86,87,90,91,92,93,96,101,105,106,108,109,110,113,114,119,121,123,127],navig:127,nc:[18,58],necessari:[20,120],necessarili:17,need:[0,1,2,3,4,9,10,11,12,14,15,16,17,18,19,22,23,27,28,31,32,33,46,53,55,57,64,65,70,71,75,82,84,86,89,90,92,96,100,112,113,114,118,120,121,122,123,124,125,127],nest:119,net:[0,27,28,29,31,33,48,84,86,113,114],netbsd:20,netcat:62,netconf:116,netdevic:123,netfilt:0,network:[17,19,23,27,28,31,33,59,84,86,113,114,116,120,123],network_cli:17,never:[0,2,4,9,12,23,100,119,120,124,127],nevertheless:15,newer:19,newli:[0,19,23,123],nexpir:19,next:[11,12,19,20,22,23,121,127],ng:[0,11,17,19,20,23],nice:[120,124],nkei:19,nname:19,nobodi:[0,17,20],node:[22,23],nois:115,nomfa:12,nomin:[11,120],non:[0,16,17,19,29,100,116,124],none:[0,2,4,12,47,59,67,99],nopam:12,nor:[4,6,14,17,42],normal:[0,4,11,14,16,17,19,24,120,121],notabl:20,notat:[27,28,29,31,33,84,86,113,114],note:[0,2,4,6,7,9,10,11,12,16,17,19,20,21,22,23,27,28,31,33,34,35,46,47,48,50,53,54,56,57,60,62,64,65,66,70,71,72,76,77,78,82,83,84,86,89,90,92,93,97,98,100,113,114,115,119,121,123,124,125],noth:[0,17,23,120],notic:[23,57,119,121],now:[4,12,14,17,19,20,21,22,115,121,123,124,127],nrpe:23,ns:19,nsub:15,nsubkei:19,ntjl0d2k2q8xtwidaqaboxuwezarbgorbgeeaylecgmdbamfagqwdqyjkozihvcn:124,ntp:19,number:[0,2,4,5,6,11,12,20,23,27,31,46,63,70,84,89,91,113,120,124,127],numer:22,nunus:15,nutshel:120,nxu3bbssuqnwi2rqhcmthjcc8rjfdzpydlw1yr:124,nxvwu0db0bq9:123,o6jr8w0x:123,o:[10,11,17,124],object:15,observ:17,obvious:[0,17,19,22,23],occur:[11,23],ofbx:124,off:[5,17,116],offici:23,offset:[0,19],often:[11,12,17,121],ok:[11,12,16,23,119],ok_no_chang:119,okai:[4,19,22,23],old:[2,4,17,23],older:[6,19],omit:[0,2,12,23,31,35,54,56,57,59,72,90,92,93,101,123],onc:[7,8,12,16,19,20,22,23,46,61,65,70,71,82,89,123,127],one:[0,1,4,9,11,12,15,16,17,18,19,20,22,23,25,27,28,31,33,46,47,60,70,73,83,84,85,86,89,94,108,113,114,119,120,121,122,123,124,125],onelin:51,ones:[1,11,12,19,23,53,91,124,126],oneself:123,onli:[0,1,2,4,5,9,11,14,15,16,17,19,20,22,23,27,31,35,46,53,54,55,56,57,60,66,70,71,72,74,75,76,83,84,85,89,91,92,93,95,96,99,100,111,112,113,115,118,119,120,123,124,125],onlin:[14,19,50],onto:[22,121],ooe2zhdpabfekqu3gtsiks7yl:123,open:[0,6,17,18,19,23,57,118,125,127],openbsd:20,openpgp:19,opensourc:17,openssh:[0,15,17,23,125],openssl:5,opensus:[20,23],oper:[12,17,18,19,118,120,125],operation:22,opposit:[16,31,33],opt:[0,11,12,19,20,21,23],option:[11,12,15,18,19,20,23,24,25,27,28,29,31,33,35,50,52,53,54,56,58,64,66,67,72,76,85,86,88,91,92,93,99,100,105,107,108,114,115,119,123,124,125],orang:57,order:[0,5,19,22,121],org:[0,4,11,19,22,27,29,59,119,121,123,124,125],organ:18,origin:[11,17,22,124],ornament:11,orphan:[1,6,19],os:[15,17,19,20,22,23,59,63],osd:11,osh:[0,1,11,16,18,19,21,23,24,25,27,28,29,31,32,33,34,35,37,38,39,40,41,42,43,44,45,46,47,48,50,52,53,54,55,56,57,58,59,60,61,62,63,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,108,109,110,111,112,113,114,115,119,121,123,124,125],osh_onli:11,other:[1,2,4,11,12,14,15,16,17,18,19,20,22,23,31,39,45,69,72,90,93,99,105,108,116,118,119,120,124,125],otherwis:[0,2,4,5,11,14,16,17,19,20,22,23,47,66],otp:[19,99],our:[0,10,11,12,17,18,19,23,121,123],out:[4,5,12,19,20,23,51,53,91,119,120,124],outdir:15,outgo:108,outlin:[12,15,23,125],output:[0,2,3,4,6,7,8,9,10,11,15,16,17,19,23,35,56,58,61,72,90,92,93,107,119,123,124],outsid:[0,120],over:[0,12,18,19,20,21,23,35,47,54,56,65,72,82,92,93],overflow:[59,121],overhead:123,overlap:0,overrid:[0,11,15,17,47,66,85,99,123,124],overridden:[0,124],overview:[45,69,105,116],overwrit:[22,23,124],ovh1:121,ovh:[0,11,12,15,17,20],ovhcloud:17,ovhcom:21,own:[0,11,12,17,19,20,23,45,69,105,106,118,120,123,124],owner:[0,11,12,18,22,44,48,57,91,105,106,120,123],ownerless:120,ownership:[11,49],p9g:124,p:[0,4,10,11,16,20,21,59,119,121],pack:119,packag:[5,18,19,23,59],packet:63,page:[18,23,116,119,124],pair:[11,19,49,58,127],pam:[0,15,17,19,20,23,91,99],pam_deni:19,pam_duo:0,pam_faillock:[0,107],pam_google_authent:[0,19],pam_success:23,pam_tal:107,pam_tally2:[0,107],pamtest:[0,12,15,20],paragraph:53,param:11,paramet:[0,10,11,12,15,16,19,20,23,118,119],paramiko:17,paramount:[19,23],paranoid:118,parent:[6,11],pars:[29,119],parseabl:29,part:[11,12,14,17,19,23,91,99,117,120,121,123,125],parti:17,partial:[5,20],particularli:[19,119],partit:20,pass:[0,2,4,10,11,15,17,19,23,64,66],passauth_dis:11,passphras:[2,4,19,20,22,45,69,105,124,127],passthrough:[116,123],passwd:[17,19,22],password:[0,11,12,15,19,20,23,27,47,49,58,59,84,91,92,99,107,113,116],passwordlen:23,past:[19,22,58,121,124,127],patch:14,path:[0,2,4,6,7,9,15,20,23,118],pattern:[17,27,28,31,33,35,54,56,72,84,86,92,93,113,114],paus:[15,52],payload:18,pbzn:124,pci:118,pem:[5,66,124],peopl:[0,17,20,53,100,120,124],per:[0,2,9,11,14,17,18,57,90],perfect:17,perfectli:120,perform:[11,20],perhap:11,period:[0,8,18],perl:[11,15,18,20,118],perlcrit:15,perltidi:15,perman:121,permiss:[11,12,22,121],permit:[19,99,120],person:[0,11,14,18,23,28,31,33,64,65,72,82,91,93,99,107,115,116,121,122,125],personalaccess:23,perspect:[0,18],pertain:[32,34,53,58,119],pf:20,pgoa5h:16,pgp:19,phase:[0,11,12,17,80,116],phone:19,pick:[19,22],pid:[6,11,19],pile:[4,23],pin:[12,121,124],pinentri:19,ping:[18,58],pinpolici:124,pipe:11,piv:[0,1,15,18,20,66,91,107,116,121],piv_ii:[121,124],pki:18,pktsz:63,pl:[0,11,19,23],place:[11,20,23,124],plai:[11,121],plain:11,plan:20,playback:11,playground:18,pleas:[0,2,4,5,12,13,15,17,19,20,22,23,28,31,33,46,64,65,68,70,71,82,89,99,112,116,121,123,124,125],plenti:4,plugin:[0,11,14,19,20,21,23,25,57,64,65,70,71,82,89,90,99,101,118,119,122,125],pm:[11,15],point:[0,4,5,17,18,22,23],polici:[8,12,17,18,59,66,85,91,99,107,116],poly1305:5,port:[0,4,10,11,15,17,21,23,27,28,29,31,33,52,58,68,76,84,86,113,114,115,119,120,121,123,125,127],port_bast:11,port_from:11,port_to:11,portion:11,portto:11,posit:[0,5,47],posix:125,possibl:[0,4,5,6,11,12,15,17,18,19,20,23,39,46,53,70,76,89,91,107,116,119,124],post:[117,120,123],potenti:[0,15,17,120,123,124],power:[0,11,17,120,121],powerus:21,ppbslfq0ddbgr:123,ppc64le:21,ppid:11,ppk:127,pr:14,practic:[18,22,120],pre:[18,119],prebuild:23,precaution:118,preced:[0,19,23,35,54,56,72,92,93],precis:[0,11,12,20,23,76,120,125],precompil:20,preconfigur:16,preexist:[23,31,105,125],prefer:[15,19,21,23,123],preferredauthent:11,prefix:[0,15,19,66,84,108,113,119],prepend:[0,23,59,124],prequisit:19,prerequisit:[18,19,20],present:[0,4,11,12,16,17,19,22,23,28,31,32,33,34,85,108,115,116,120],preserv:22,press:[19,121],pretti:4,prettifi:119,prevail:47,prevent:[0,17,84,100,107,113,118],previou:[0,16,20,23,46,70,89,100,123],previous:[15,23,124,125],primari:[10,23,123],primit:118,principl:18,print:[0,11,58,92,119,123],printf:[15,19,51],prior:22,privat:[5,14,15,17,19,20,22,23,49,58,74,95,115,120,121,123,124,127],privileg:[0,5,22,118,120],pro:120,proactiv:[0,12],probabl:[0,4,9,10,17,19,123],probe:23,problem:[0,4,17,19,20,125],proce:[0,11,19,22,23],procedur:[0,10,18,19,20,22,23],proceed:20,process:[0,5,11,12,17,18,19,20,118,120,123,124],produc:[0,4,11],product:[1,11,15,18,20,21,29,118],profil:19,program:[0,11,17,23,119,125],prohibit:[121,123],promot:19,prompt:[12,19,20,45,66,67,69,77,78,85,105,108,123,127],propag:19,proper:[0,7,15,18,20,116,121,123,124,127],properli:[17,19,20,23,99,113,121,123,124],properti:11,protect:[2,4,12,19,127],proto:[27,28,31,33,84,86,113,114],protocol:[18,23,27,28,31,33,64,84,86,113,114,116,119,125],prove:[19,124],provid:[0,5,11,12,14,15,17,18,19,23,123,124],provis:[120,123],proxi:[1,11,17,18,23,58,116,121],proxycommand:18,proxyhttp_daemon:11,proxyhttp_work:11,pseudo:127,pub:19,pubkei:[12,19,23,99,116],public_kei:11,publickei:[0,11,12,19,121],publicli:23,publish:[13,19,20],pull:15,puppet:[18,23,120],purpl:57,purpos:[23,112,120],push:[0,2,10,11,14,23,121],push_opt:19,push_remot:19,put:[2,22,73,94],putti:[11,18,126],puttygen:127,pwem8r:124,pwgen:[19,20],python:[15,17],q:[10,19,23],qf0m:123,qo:123,qr:19,qrcode:19,queri:[5,18],quick:[18,19,45,69,105,116,124],quickli:[0,18,120],quiet:119,quit:[11,12,17,121],quot:[0,11,23,24,27,31,52,66,84,85,88,108,113],r0:16,r:[0,14,19,65,119],ram:17,ran:118,random:[17,19,127],rang:[0,84,85,113],rapidli:19,rare:[0,11],rather:11,rational:119,raw:15,rbrrgs66apiepc:123,rc1:123,rc2:20,rc9:121,rc:5,re:[0,1,4,9,11,12,15,16,17,18,19,20,21,22,23,24,27,31,44,45,52,60,66,69,82,83,84,85,105,108,113,115,118,119,120,121,122,125],reach:5,read:[2,4,11,12,17,18,19,20,21,46,65,70,71,82,89,118,119,124],readabl:[2,4,11,12,14,22,92,118,119],readi:[5,19,21,23,121],readlin:11,readm:23,readonli:[11,19],readonlyslavemod:19,real:[19,118],realiz:17,realli:[0,18],realm:[107,116],realmcreat:[18,107],realmdelet:[18,107],realminfo:[18,107],realmlist:[18,107],realopt:11,reaper:1,reason:[0,12,17,19,23,24,68,88,121,125],reboot:[19,22],rebuild:15,recal:121,receiv:[0,11,19],recent:[4,14,17,19,23,91],recipi:19,recommend:[18,19,23],record:[0,4,18,20,23,116,121],recurs:65,red:57,reduc:[17,20],refer:[11,12,18,23,116,124],referenc:[11,12,15,16,22],refin:[35,54,56,72,92,93],reflect:23,refus:[2,4,10],regard:[59,99],regardless:[0,5,12,17,19,22,100],regener:20,regex:[0,16,119],regist:[17,59],regul:17,regular:[19,65,82,124],regularli:20,relat:0,relax:100,releas:[14,17,20,22,23,117],relev:11,reli:[11,12,19,99,119],relianc:116,reload:12,remain:[7,11,23,121],rememb:[120,123],remot:[0,11,12,14,15,16,17,18,21,22,23,27,28,31,33,46,53,58,59,70,73,76,84,86,89,94,113,114,115,116,118,120,121,123,125],remote_account_nam:21,remote_admin_user_nam:15,remote_host:[21,123],remote_machine_host_or_ip:21,remote_port:123,remote_us:123,remote_user_nam:15,remotebackup:4,remotehost:64,remotehostlist:19,remoteip:11,remov:[0,1,4,7,8,11,12,23,30,36,47,48,49,58,68,99,107,119],renam:20,renew:0,repeat:[11,20],repeatedli:12,replac:[0,11,20,22,23,30,51,57,119,124,125],replai:[58,121],repo:20,report:[13,14,29,61],repositori:[15,19,20],repres:[11,23,120],repudi:19,request:[0,5,11,12,14,15,23,82,123,124],requested_by_the_sword_master_of_melee_island_see_ticket_no_1337:11,requir:[0,11,14,16,17,20,23,46,47,59,70,71,77,78,89,91,97,98,99,100,121,123,124,125],requisit:19,research:[45,69,105],reset:0,resid:[12,23],resolut:0,resolv:[11,27,28,31,33,35,56,72,84,86,93,113,114],resort:0,resourc:19,resp:11,respect:[11,14,29,127],respons:[2,3,4,5,6,7,8,9,10,18,23,120,123],rest:[22,126],restart:[19,22,23],restor:[2,18,19,20,100,121,123,124],restrict:[0,18,19,20,44,47,57,91,106,118,121,123],result:[0,11,15,23,35,54,56,72,76,92,93],resum:[17,19,20],retcod:121,retir:23,retriev:120,returnvalu:11,rev:19,revers:[0,11,35,56,72,93],reversedn:119,revert:100,review:[1,14,18,19,23,122],revoc:19,revok:107,rid:9,right:[0,11,12,14,16,19,39,46,57,64,65,70,71,72,82,89,90,93,115,118,120,123,124,125],rm:17,rmpocaypsfrqmobfojver5ulqxyjqytrdguoquwh2na:121,robin:19,robot:[12,17,119,120,123],robust:[45,69,105],rocki:23,rockylinux:[20,23],rogu:120,role:[0,11,18,49,53,91,116,122],root:[0,2,4,5,10,11,12,14,16,17,18,22,23,29,107,120,121],root_ssh_key_path:15,rootlistingresskei:[18,107],rotat:[11,18,23],rough:18,round:19,router12:123,routin:20,row:[0,11,21,23],rpm:[20,23],rsa:[0,5,11,19,22,23,45,59,69,105,124],rsh:[4,10,19,64],rss:19,rsync:[0,1,10,18,19,23,27,28,31,33,58,65,82,84,86,113,114],rsyncfilt:[4,23],rsyslogd:19,rtkit:19,rule:[0,12,17,121],run:[0,2,3,6,7,8,9,11,12,18,19,20,21,22,23,29,52,57,58,65,82,118,125],runtim:0,rvzbzxiylrcswzmrurtobtonrvjtz3cj5zpjazycrjq:124,rysnc:125,s390x:21,s:[0,4,5,11,12,14,16,17,19,20,21,22,23,30,31,33,63,64,65,73,82,84,85,86,91,93,94,95,99,100,108,113,114,118,119,120,121,122,123,124,125,127],safe:[11,19],safeti:118,sai:[0,10,17,19,121],said:[0,100,120],same:[0,11,12,14,16,17,19,20,22,23,48,57,60,84,99,113,119,120,123,125],sandbox:18,sane:[0,1,19,23],satellit:[11,18,23],save:[15,20,124,127],sbin:[0,19],sbp5jj83drrwzks57hf3q0lotbn27vm:124,sc2034:15,scale:120,scheme:116,scope:[12,19,120,124],scp:[2,14,18,19,22,23,27,28,31,33,58,64,82,84,86,113,114,116],scp_bastion:65,scp_script:65,scpdown:[23,27,28,31,33,65,84,86,113,114,125],scpserver:125,scpup:[23,27,28,31,33,65,84,86,113,114,125],scratch:2,screen:11,screensav:17,script:[0,2,3,4,5,6,7,8,9,10,11,15,16,17,18,19,20,22,23,65,82,118,119],se:[12,90,124],search:[18,118],sec:19,second:[0,4,5,6,10,11,12,18,19,21,23,27,31,62,63,84,85,100,113,121],secondari:[7,10,16,19,29],secret:[2,4,19,23],section:[5,11,12,13,15,18,19,20,21,22,23,120,121,122,125,126],secur:[0,2,4,14,15,17,18,19,20,23,116,117,120,121,123,124,125],securegroup:12,see:[0,2,4,5,8,11,12,14,15,16,17,19,20,21,22,23,25,32,34,35,53,54,56,64,72,77,78,84,85,92,93,97,98,99,100,115,116,119,120,121,123,124,125],seek:17,seem:[17,22,121,125],seen:[0,11,12,17,19,23,25,31,47,91,102,118],segv:11,select:[85,127],self:[0,11,23,116],self_remote_user_onli:[84,113],selfaddingresskei:[0,18,58,121,124],selfaddkei:85,selfaddpersonalaccess:[0,14,18,21,23,64,65,73,82,107,121,123,125],selfdelingresskei:[18,58],selfdelkei:85,selfdelpersonalaccess:[0,18,23,107],selfforgethostkei:[18,58],selfgenerateegresskei:[11,18,58],selfgeneratepassword:[18,23,58,123],selfgenerateproxypassword:[18,58,123],selflistaccess:[12,18,58,121],selflistegresskei:[18,21,23,51,58,64,82,84,113,120,121],selflistingresskei:[18,51,58,67,124],selflistpassword:[18,23,58,113,123],selflistsess:[0,4,11,18,58,81,121],selfmfaresetpassword:[18,58],selfmfaresettotp:[18,58],selfmfasetuppassword:[12,18,58],selfmfasetuptotp:[12,18,58],selfplaysess:[0,4,11,18,58,121],selinux:23,send:[0,15,19,63,100,123,124],sens:18,sensit:[0,12,17],sent:[4,19,118],separ:[2,10,11,19,25,52,108,118,120],sequenti:[12,58],seri:119,serial:124,serialno:124,seriou:[17,21],serv:15,server12:29,server42:121,server:[0,3,4,5,9,11,14,15,18,19,22,23,29,30,32,34,36,37,40,47,53,58,59,99,107,116,118,119,122,123,125],serversid:0,servic:[5,17,20,22,123],session:[1,11,12,18,20,58,59,99,116,120,122,127],set:[0,2,3,4,5,6,7,8,9,10,11,12,14,16,18,19,20,22,23,24,32,37,38,39,43,46,47,48,63,70,71,77,78,85,89,91,97,98,99,100,120,122,124,127],setup:[0,14,18,19,21,22,23,58,121,123,124,125],sever:[11,12,14,15,18,20,21,23,31,58,90,118,123,124,125],sf5pdidlwsidkcv95qnwhx0:123,sftp:[14,18,22,23,27,28,31,33,58,64,65,84,86,113,114],sftp_bastion:82,sftp_script:82,sg8bb:123,sgid:19,sh:[1,15,16,19,20,21,23],sha256:[5,12,121,124],sha256crypt:123,sha384:5,sha512:23,sha512crypt:123,shadow:17,shaki:0,shall:[19,123,124],share:[11,19,23,99],sheet:[45,69,105],shell:[11,15,16,17,23,24,27,28,31,33,52,66,84,85,86,88,108,113,114,118,119,125],shellcheck:15,ship:23,should:[0,1,2,4,5,10,11,12,14,15,16,19,20,21,22,23,27,28,29,31,46,52,57,64,65,70,71,74,82,84,86,89,95,113,114,118,119,120,121,123,124,125,127],shouldn:[19,118,119],show:[15,53,55,58,59,91,92,93,110,115,121,124],show_fortun:59,shown:[0,23,27,31,52,76,84,85,88,113,127],sibl:[44,76,106],side:[0,4,11,12,19,20,59,91,108,116,118,123],siem:[0,116,124],sign:[19,23,124],signal:11,signatur:18,signing_kei:19,signing_key_passphras:19,sigterm:19,sigusr1:0,silent:0,similar:[0,19,23,120,123],similarli:17,simpl:[0,2,16,18,23,35,51,54,56,72,92,93,119,120],simpli:[4,17,19,20,22,23,50,57,65,82],simplifi:17,simultan:17,sinc:[0,9,13,23],singl:[4,11,18,84,113],sit:120,sixth:18,size:[0,5,11,19,23,45,46,59,63,69,70,84,89,105,113],sk:[0,15,23],skip:[0,11,12,15,20,21,29,44,52,106,123],slave:[0,4,22],slesimpl:123,slot:124,slow:[35,53,56,72,91,92,93],slower:121,slt14lllvqs6ajaxb7fm4bajg:124,smartphon:12,snakeoil:5,snapd:19,snipper:12,snippet:[19,66,124],snsl:19,sntrup761x25519:23,so:[0,7,11,12,15,17,18,19,20,22,23,27,28,31,33,53,58,84,86,95,100,113,114,118,119,120,121,123,124,125,127],soc1:118,soc2:118,softwar:[0,11,17,20,23],sole:120,some:[0,2,5,6,9,11,12,15,17,18,19,20,23,39,57,58,88,99,107,112,115,118,119,121,122,124,125,126],somebodi:[11,17,20,49,90,120,125],somebodyels:25,somegroup:11,someon:[14,120],someth:[0,11,17,19,121],sometim:[12,17,124],somewhat:17,somewher:[0,12,19,20],soon:[4,46,58,70,89,124],sorri:[0,12,125],sound:[19,120],sourc:[4,11,15,16],space:[0,2,4,10,11,19,29],spare:0,spars:7,spawn:[11,15,123],speak:20,spec:15,special:[0,16,27,28,31,33,84,86,113,114,121,124],specif:[0,11,12,18,25,32,34,36,53,57,65,82,90,91,100,115,118,119,120],specifi:[0,4,5,10,11,15,16,19,20,23,25,27,28,29,31,32,33,34,37,38,39,40,41,42,43,45,46,47,52,53,63,66,67,69,70,76,84,86,89,92,97,98,99,100,105,111,113,114,115,121,123,125],speed:[11,15,19,20,45,69,105,121,124],speedup:19,sphinx:15,split:[23,116,123],sqejb8y5aerdaepiiz:124,sqgv:123,sql:[0,11,23],sqlite3:118,sqlite:[0,4,18,23],sqm:124,src:65,srcdir:64,srv123:11,srv1:[0,27],ss:[19,76],ssd:[17,127],ssh:[2,4,10,11,14,15,16,20,21,22,23,27,46,50,55,59,64,65,66,68,70,71,73,74,75,76,82,85,89,91,94,95,96,99,100,105,108,113,116,118,119,120,121,123,124,125,127],ssh_config:[12,16,19,20,23,99],ssh_key_path:15,ssh_port:15,ssha:11,sshd:[0,12,19,23,29,99],sshd_config:[19,20,23],sshfp:18,sshing:18,ssl:[5,19],stabl:[20,23],stack:23,staff:19,stage:12,stai:20,stan:11,stand:[17,18],standalon:0,standard:[0,2,10,16,20,22,23,116],standpoint:17,start:[0,1,2,5,6,7,10,11,15,17,19,20,23,76,119,121,124,127],stat:19,state:[19,23],statu:[0,5,18,91,99],stderr:[0,11,116],stdin:[12,17,29,58,66],stdout:[0,116],step:[12,15,18,19,20,52,80,122,124],still:[0,3,4,6,11,17,19,23,34,100,116,121,123,124],stock:23,stop:[12,19,20,22,23],storag:[4,11,20],store:[0,11,17,19,20,23,123,124],straightforward:23,strang:121,strftime:0,strict:[17,99],stricthostkeycheck:[10,99],strictli:[18,20,47,121,123],strike:120,string:[0,2,3,4,5,6,7,8,9,10,16,23,27,35,54,56,72,84,85,92,93,100,108,113,119],strip:22,strong:124,strongli:22,structur:119,stub:11,stuff:17,style:[5,23,125],sub:[4,15],subdir:4,subfold:23,subject:120,submit:15,subnet:0,subsect:[12,122],subsequ:[0,85],subset:[15,120],subsystem:[23,27,28,31,33,82,84,86,113,114,116,125],succe:119,succeed:[118,119],success:[0,4,17,19,119],successfulli:[11,12,19,23,121,124],suddenli:23,sudo:[0,11,25,118],sudo_us:11,sudoer:[0,20,118],suffic:23,suffici:127,suggest:19,suid:19,suitabl:90,summar:17,sundai:20,superown:[0,11,91,120,121],supersecretserv:11,supplementari:20,support:[0,5,8,15,18,19,20,22,27,28,31,33,35,46,54,55,56,59,64,65,70,71,72,75,82,84,86,89,92,93,96,108,113,114,116,123],suppress:99,sure:[0,12,15,19,21,22],surfac:119,suspect:13,swap:19,sxvenbvxury0v8sblehspyaxg:124,sy:19,sync:[1,4,12,23],synchron:[4,23],syncid:19,syntax:15,sysadmin:[4,18,120],syslog:[0,2,3,4,6,7,8,9,17,18,20,23,116,118],syslog_host:11,syslog_tim:11,sysret:11,system:[0,2,5,11,12,15,17,18,19,22,23,85,112,118,120,121,123,125],systemctl:[5,19,23],systemd:[5,19],sysus:11,sysv:5,syswrit:11,t:[0,2,4,5,6,7,8,9,10,11,12,14,15,16,17,18,19,20,21,22,23,25,27,29,46,52,54,55,57,59,61,63,66,70,72,75,77,78,79,84,85,87,89,92,93,96,97,98,99,100,102,105,113,115,118,119,120,121,123,124,125,127],tab:[12,121],tabl:[0,45,69,105],tag:[12,20,23,120],tail:[17,19,20,23],tailor:[0,19],taint:[17,118],take:[0,5,12,15,17,19,23,35,54,56,72,92,93,119],takeawai:124,taken:[12,16,20],talk:17,tamper:[19,118],tank:121,tar:[2,19,20,22],tarbal:20,target:[14,15,16,99],task:[1,2,3],tcp:58,tdy:15,team:[18,116,120],tear:17,technic:[17,18,120,125],technolog:17,tell:[0,11,12,115],telnet:[0,11,46,70,89,116],templat:[0,11,12,19,20,23],temporari:[8,18,22,32,100],temporarili:14,ter:11,term:[11,120],termcap:11,termin:[0,6,17,18,19,119,123],test1:16,test2:16,test3:16,test:[0,5,10,18,19,20,21,23,62,121,123],testbast:59,tester:16,testgroup1:91,text:[0,11,16,23,27,31,35,56,61,66,72,84,93,113,119],than:[0,4,6,10,11,12,18,19,22,23,47,48,84,113,119,120,123,124],thank:124,thei:[0,4,8,11,12,14,16,17,19,20,23,31,34,73,90,94,95,118,120,121,123,124],them:[0,2,4,11,12,14,15,19,23,57,100,102,120,124,127],themonkei:11,themself:120,themselv:[0,23,90,95,120],therefor:0,theses:23,thi:[0,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,27,28,31,32,33,34,35,37,38,39,40,42,43,44,45,46,47,48,50,53,55,56,58,60,62,63,64,65,66,68,69,70,71,72,73,74,76,77,78,82,83,84,85,86,89,90,91,92,93,94,95,97,98,99,100,102,105,106,107,108,113,114,115,116,118,119,120,121,122,123,124,125,126,127],thing:[0,11,16,18,120,121],think:[17,115],third:[0,18],those:[0,4,11,12,15,17,18,19,20,23,54,73,94,120,121,124],though:[4,23],thousand:[17,84,113],three:[11,120],through:[0,2,3,4,6,7,8,9,10,11,12,14,15,17,18,19,20,21,23,27,28,29,31,33,58,66,72,76,84,85,86,93,99,113,114,115,116,119,120,121,122,125],thu:[12,91],thumb:[0,17],ti:[73,74,94,95,125],ticket:124,tidi:15,tidycheck:15,time:[0,1,4,5,6,9,10,11,12,15,16,17,19,20,22,35,54,56,59,72,85,92,93,99,100,120,121,123,124,127],timeout:[0,16,19,47,62,63,83],timeouthandl:11,timestamp:[11,76,124],timestampend:11,timestampendusec:11,timestampusec:11,timesyncd:19,tl:[5,17],tmp:[16,22,65],todai:[59,121],togeth:23,token:[0,23,66,100,124],tolow:19,too:[0,4,19,20,23,120,123],tool:[18,20,23,58,120,124,127],top:127,topic:17,total:[19,121],totp:[0,12,15,19,20,23,47,58,59,91,99,107],touch:[4,19,20,23,124],touchpolici:124,tp:21,tq1p7zyraot4woh1zcgjnf:123,trace:11,traceabl:[5,11,18,120],tracerout:58,track:118,trade:116,traffic:[4,5],trail:2,transfer:[4,22,58],transmit:49,transpar:[11,20,23],trick:[5,118],trigger:[0,11,12],trip:123,trust:[4,14,17,19,107,116,118],trustdb:19,ttl:[3,11,23,27,31,47,63,84,85,91,100,113,124],tty:[0,6,11,18,19],tty_group:11,ttyplai:11,ttyrec:[0,2,4,9,17,18,20,23,58,116,121],ttyrecfile:11,ttyrecfilenameformat:11,ttyrecs:23,tue:123,tupl:[27,28,31,33,84,86,113,114,120,123],turn:[5,124],tutori:18,tvzf:22,twice:[11,23,24,27,31,52,84,85,88,113,127],two:[0,11,12,15,17,19,21,22,23,116,119,120,121,123,124,125],txt:51,type8:23,type9:23,type:[0,2,3,4,5,6,7,8,9,10,12,14,18,19,20,21,23,76,121,123,127],typic:0,u:[0,123],uaih09nxpbf4ejpruroi:123,ubuntu:[20,23],udw2unl:123,ui:14,uid:[0,11,85,121],uid_auto:11,ultim:[4,15,19],umask:23,unauthor:[121,123],unavoid:18,uncom:[12,19],uncondition:[12,63],unconfigur:[2,4],under:[0,11,12,15,18,19,20,21,22,23,27,31,33,66,84,85,108,113,118,125,127],underli:[15,23,59,112],underneath:17,understand:[11,16,17,120],undo:60,unencrypt:[2,20],unexpect:11,unexpir:107,unfreez:107,uninstal:23,uniqid:[0,11,23,124],uniqu:[11,18,121],unit:5,unix:[0,11,47,58,85,91,99,107,118],unless:[0,2,9,23,46,70,71,89],unlock:[2,4,17,18,24,58,60,107],unmodifi:12,unprivileg:[0,118],unset:[0,24,99],unsupport:[0,20],unsur:19,untar:20,until:23,untouch:23,untrust:17,unus:[15,17],unusu:11,up:[0,2,3,4,5,7,10,11,12,14,15,17,18,19,20,21,22,23,122,124],upcom:0,updat:[5,11,19,23,120],upgrad:[14,18,20],upl:0,upload:[23,27,28,31,33,64,65,82,84,86,113,114,116,125],upper:85,uppercas:119,uri:123,url:0,us:[0,2,3,4,5,6,7,8,9,10,11,14,16,18,19,20,22,23,27,28,31,33,35,46,47,48,50,52,53,54,56,57,58,60,62,66,68,70,72,73,74,76,81,84,85,86,89,91,92,93,94,99,100,102,105,106,108,112,113,114,116,118,120,121,122,123,124,125,126],usabl:[4,15,27,31,33,84,113],usag:[0,11,12,15,20,21,23,58,107,119,126],usec:[0,11],useless:[20,123],user12:25,user1:[51,59,91],user2:51,user3:51,user:[0,2,4,7,9,10,11,15,16,17,18,19,20,21,23,26,27,28,29,31,33,44,51,52,57,76,84,86,88,95,113,114,115,118,119,120,121,123,124,125],usercom:119,userknownhostsfil:99,usernam:20,usr:[0,11,15,19,23],usual:[0,5,11,12,15,16,17,18,19,20,22,23,82,119,121,123,124,127],utc:[12,91,121,124],utf8:19,utf:0,uz:124,v00:123,v3:[14,20,91],v6:21,v7:21,v9axndt0dnuo7adpzxa7i7xpbrkisbep7rcqxgs5cbqgcbq:124,v:[0,19,124],va:64,valid:[0,4,11,12,15,19,23,29,65,82,85,100,120,124,125],valu:[0,2,3,4,5,6,7,8,9,10,11,12,15,16,19,23,47,99,107],value1:[11,16],value2:16,variabl:[16,19],variant:[20,119],vault:19,vdi:20,ve:[0,10,11,12,16,17,19,22,65,82,119,120,121,123,124,127],vector:14,verbos:[90,92],veri:[5,11,17,23,84],verif:5,verifi:[0,12,15,19,20,23,68,100,121,123,124,127],version:[0,11,14,18,19,20,22,119,124,125],via:[12,14,76,120,121],view:[15,17,23,107,124],vim:[19,20],vimdiff:20,violat:0,virtual:116,vjorh7huvoi:124,vlixbqelf07mkqofdebx:124,vm:[15,125],volum:[15,17],voxms8:123,vpn:20,vsn6kpxu5jud7scnbkynh:123,vsz:19,vulner:23,w150:19,w:[0,19,62,63],wa:[0,10,11,12,17,19,22,23,28,33,86,91,114,119,121,124],wai:[0,4,5,10,11,12,17,18,20,21,22,23,46,62,70,71,89,92,99,120,124,125],wait:[0,4,12,50,120,121],want:[0,2,4,5,9,11,12,15,16,18,19,20,21,22,23,25,28,31,33,46,50,53,57,89,97,98,100,119,120,121,124,125],warmli:[11,19,20,45,69,105],warn:[0,17,19,20,22,23,68,91,121],wast:121,watch:[11,19],watcher:[1,4,19,23],water:121,we:[0,2,3,4,5,6,7,8,9,10,11,12,16,17,19,20,21,22,23,25,31,52,62,108,119,120,121,122,123,124],weak:11,websit:17,wed:[12,19,123,124],welcom:[12,121],well:[0,11,17,20,117,118,120,124],were:[0,4,11,19,22,23,83,124],weren:120,what:[0,4,5,11,12,19,20,99,115,121,123,124],when:[0,2,3,4,5,6,7,10,11,12,14,15,16,17,19,20,22,23,47,59,68,76,84,85,99,100,102,108,113,120,121,123,124,125,127],whenev:23,where:[0,2,4,6,7,9,10,11,12,14,15,16,17,19,22,23,65,82,120,121,125],wherea:23,whether:[0,5,10,11,12,16,17,19,22,23,29,53,58,91,92,118,119,123],which:[0,1,2,3,4,5,6,7,8,9,10,11,12,14,15,16,17,18,19,20,21,22,23,25,27,28,29,31,32,33,34,35,37,38,39,40,42,43,46,48,52,54,59,84,85,86,89,97,98,99,100,113,114,115,118,119,120,121,123,125,127],whichev:120,whitelist:59,who:[112,120,122],whoever:17,whohasaccessto:[18,107],whole:[18,27,28,31,33,60,83,84,86,113,114,120,121],whoopsi:19,whose:[11,12,23,92,120],why:[12,18,19],wide:[0,17,20,84,99,100,113,123,124],widen:119,wider:[0,84,113],widespread:126,widest_v4_prefix:[84,113],wik3vf:123,wiki:11,wildcard:[23,35,54,56,72,92,93,115],window:[125,127],winscp:125,wip:18,wise:[0,17],wish:[4,127],wit:119,within:[0,12,21,23,119],without:[0,2,4,6,7,9,10,11,12,14,17,18,19,20,21,23,35,47,53,54,56,57,72,90,91,92,93,113,115,116,119,120,125],won:[0,2,4,6,7,8,9,10,11,17,22,23,85,115,124,125],woosh:121,word:[0,4,11,16,39,72,93,120,125],work:[0,2,10,11,12,15,16,17,18,19,22,23,46,59,70,84,89,90,91,93,96,99,100,101,102,104,119,120,121,122,123,124,125],worker:11,workflow:[0,17,18,124],workload:[17,123],worst:23,worth:11,worthless:20,woscsi8hhggqxqiqedmnt6cwz83qk73:124,would:[0,4,11,12,14,17,19,20,23,84,113,119,120,121,123,124,125],wouldn:[18,118],wrapper:[17,23,125],write:[0,2,4,6,7,9,10,11,17,18,19,20],written:[0,2,4,6,7,9,10,11,17,23,51],wrong:[19,44,87,106],wsl:125,wyxpsedztxgael12ecplisyddqkt3ejfudainbpf:124,x1yfk8gah9dzanbgkqhkig9w0baqsfadah:124,x8:123,x:[15,19,20,23],xgh:124,xmys2u:23,xvzf:22,xxmcgvre6cwx7aa0hchdet0synoizotglxvxqr:124,xzvf:22,y:[0,11,19,123],ydkk8wmvlvavcbglx:23,ye:[12,17,19,53,79,99],year:[0,23],yet:[4,20,23,116,127],yield:16,ylwsjseiknzmscqcdicslrdkxpgmok8ocxu0err4yvfxiszzl32btzyld8n7i:124,ynhzjpxza4r838xkg2tfvvov:123,you:[0,1,2,3,4,5,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,27,28,31,32,33,41,44,45,46,50,52,53,54,57,58,59,60,64,65,66,67,69,70,71,74,77,78,82,83,84,85,86,87,88,89,90,92,97,98,100,105,106,108,113,114,115,119,120,121,122,123,124,125,127],your:[0,2,3,4,5,6,7,8,9,10,11,12,14,15,16,17,18,19,21,22,23,27,28,31,33,45,49,51,58,59,65,71,72,82,84,85,86,105,107,108,119,120,121,123,124,125,127],your_mgmt_kei:124,yourself:[11,15,17,20,21,23,44,48,66,73,74,87,106,122,123],yqflux17tuwe1jfhhax:123,yrlxzt0t7wbs3e:23,yubico:[15,20,116,124],yubikei:124,yyyi:[22,76],yyyymm:[0,11,23],z0:119,ze7px3olxdjwthsrdnzelm6avzt2kszx:123,zero:[0,5,16,47,85,99],zkw01n2kt:124,zone:19,zstd:0,zxf:20},titles:["bastion.conf","Configuration files","osh-backup-acl-keys.conf","osh-cleanup-guest-key-access.conf","osh-encrypt-rsync.conf","osh-http-proxy.conf","osh-lingering-sessions-reaper.conf","osh-orphaned-homedir.conf","osh-piv-grace-reaper.conf","osh-remove-empty-folders.conf","osh-sync-watcher.sh","Logs","Multi-Factor Authentication","Security Advisories","CVE-2023-45140","Environment setup","Writing tests","FAQ","Welcome to The Bastion documentation!","Advanced Installation","Basic Installation","Sandbox using Docker","Restoring from backup","Upgrading","adminMaintenance","adminSudo","admin plugins","groupAddServer","groupDelServer","groupSetServers","group-aclkeeper plugins","groupAddGuestAccess","groupAddMember","groupDelGuestAccess","groupDelMember","groupListGuestAccesses","group-gatekeeper plugins","groupAddAclkeeper","groupAddGatekeeper","groupAddOwner","groupDelAclkeeper","groupDelEgressKey","groupDelGatekeeper","groupDelOwner","groupDestroy","groupGenerateEgressKey","groupGeneratePassword","groupModify","groupTransmitOwnership","group-owner plugins","alive","batch","clush","groupInfo","groupList","groupListPasswords","groupListServers","help","open plugins","info","lock","mtr","nc","ping","rsync","scp","selfAddIngressKey","selfDelIngressKey","selfForgetHostKey","selfGenerateEgressKey","selfGeneratePassword","selfGenerateProxyPassword","selfListAccesses","selfListEgressKeys","selfListIngressKeys","selfListPasswords","selfListSessions","selfMFAResetPassword","selfMFAResetTOTP","selfMFASetupPassword","selfMFASetupTOTP","selfPlaySession","sftp","unlock","accountAddPersonalAccess","accountCreate","accountDelPersonalAccess","accountDelete","accountFreeze","accountGeneratePassword","accountGrantCommand","accountInfo","accountList","accountListAccesses","accountListEgressKeys","accountListIngressKeys","accountListPasswords","accountMFAResetPassword","accountMFAResetTOTP","accountModify","accountPIV","accountRevokeCommand","accountUnexpire","accountUnfreeze","accountUnlock","groupCreate","groupDelete","restricted plugins","realmCreate","realmDelete","realmInfo","realmList","rootListIngressKeys","selfAddPersonalAccess","selfDelPersonalAccess","whoHasAccessTo","Features","Principles","Security","JSON API","Access management","First steps","The basics","HTTPS Proxy","PIV keys support","SFTP, SCP & RSYNC support","Specific SSH clients tutorials","Using PuTTY with The Bastion"],titleterms:{"0":20,"00":23,"01":23,"02":23,"03":23,"04":23,"05":23,"06":23,"07":23,"08":23,"09":23,"1":[20,125],"10":23,"11":23,"12":23,"13":23,"14":23,"140":18,"15":23,"16":23,"17":23,"18":23,"19":23,"2":[20,125],"20":23,"2020":23,"2021":23,"2022":23,"2023":[14,23],"2024":23,"21":23,"22":23,"23":23,"25":23,"27":23,"28":23,"2fa":19,"3":20,"30":23,"4":20,"45140":14,"5":20,"6":20,"7":20,"8":20,"9":20,"99":23,"boolean":23,"import":[19,22],"new":[29,45,46,66,69,70,71,85,89,108],"public":[45,66,67,69,73,74,94,95,112],"try":123,And:120,For:123,IT:120,On:12,The:[17,18,23,122,127],about:[53,59,91,110],access:[3,11,31,33,35,72,79,80,84,86,90,93,101,113,114,115,120,121,123,125],account:[0,11,12,14,19,20,22,31,32,33,34,35,37,38,39,40,42,43,66,67,68,69,70,73,74,75,76,77,78,79,80,84,85,86,87,88,89,91,92,93,94,95,96,97,98,99,100,102,103,104,113,114,115,124],accountaddpersonalaccess:84,accountcr:85,accountcreatedefaultpersonalaccess:0,accountcreatesupplementarygroup:0,accountdelet:87,accountdelpersonalaccess:86,accountexpiredmessag:0,accountexternalvalidationdenyonfailur:0,accountexternalvalidationprogram:0,accountfreez:88,accountgeneratepassword:89,accountgrantcommand:90,accountinfo:91,accountlist:92,accountlistaccess:93,accountlistegresskei:94,accountlistingresskei:95,accountlistpassword:96,accountmaxinactivedai:0,accountmfapolici:0,accountmfaresetpassword:97,accountmfaresettotp:98,accountmodifi:99,accountpiv:100,accountrevokecommand:101,accountuidmax:0,accountuidmin:0,accountunexpir:102,accountunfreez:103,accountunlock:104,acl:[2,11,29],aclkeep:[30,37,40],acronym:57,activ:[2,3,6,7,8,9],add:[27,31,32,37,38,39,66,84,113],addit:[12,79,80],admin:[19,26],adminaccount:0,administr:18,adminmainten:24,adminsudo:25,advanc:19,advisori:13,alia:121,aliv:50,all:[12,60,83],allow:19,allowedegresssshalgorithm:0,allowedingresssshalgorithm:0,allowednetwork:0,alreadi:17,alwaysactiveaccount:0,an:[27,28,31,32,33,34,35,37,38,39,40,42,43,67,79,80,84,86,87,88,89,91,94,95,96,97,98,99,100,102,104],anoth:[18,25],ansibl:17,answer:50,api:119,ar:[17,19,22],archiv:22,ask:120,associ:[75,96],audit:118,authent:[12,19],autom:12,avail:[15,19,54],back:22,backup:[2,19,22],base:14,basi:12,basic:[20,53,122,125],bastion:[0,17,18,19,20,24,41,54,59,63,64,65,68,69,71,82,85,87,92,93,109,110,111,112,121,127],bastioncommand:0,bastionnam:0,batch:[12,51],been:23,behavior:9,block:[27,28,56],bypass:12,can:17,central:120,charact:18,check:[20,62],cipher:5,cleanup:3,client:126,close:11,clush:52,cluster:19,code:[11,20],color:57,command:[51,52,90,101,119],commit:15,common:17,conf:[0,2,3,4,5,6,7,8,9],configur:[1,5,12,19,20,23,47,59,78,84,98,99,113],connect:[19,20,88,112,121],contain:16,content:[11,12,15,16,119,123,124,125],core:118,creat:[19,20,45,69,85,105,108],credenti:[79,80],crowd:120,current:[29,60,83],cve:[13,14],daemon:10,daystokeep:2,debug:0,decentr:120,declar:[108,123],decrypt:22,defaultaccountegresskeyalgorithm:0,defaultaccountegresskeys:0,defaultlogin:0,delet:[44,87,106,109],destdir:2,destin:4,detail:[12,14],develop:18,die:11,displai:[59,91,110],displaylastlogin:0,dn:19,dnssupportlevel:0,docker:[15,17,21],document:18,documentationurl:0,doe:17,ed25519:23,egress:[0,41,46,55,70,73,75,89,94,96,123],egresskeysfrom:0,els:48,empti:9,enabl:[2,3,5,6,7,8,9,10,19],enableaccountaccesslog:0,enableaccountsqllog:0,enableglobalaccesslog:0,enableglobalsqllog:0,enablesyslog:0,encrypt:[2,4,19,20],encrypt_and_move_to_directori:4,encrypt_and_move_ttyrec_delay_dai:4,encrypt_and_move_user_logs_delay_dai:4,encrypt_and_move_user_sqlites_delay_dai:4,enhanc:23,ensur:[19,22],environ:15,error:125,error_cod:119,error_messag:119,even:57,exactli:18,exampl:[16,53,59,64,84,91,113,119],exist:17,exit:50,expand:93,expir:102,explan:12,extract:22,factor:12,fanci:0,faq:17,featur:116,fed:51,few:76,file:[1,4,11,19,23,64,65,82],first:[20,121,123],flavor:12,folder:9,forbiddennetwork:0,forget:68,format:[11,119],freez:88,from:[22,28,33,34,40,42,43,63,64,65,67,68,82,86,87,88,114],frozen:103,gatekeep:[36,38,42],gatewai:18,gener:[19,23,46,70,71,89],get:20,gid:[19,22],git:15,given:[93,115],global:[0,120,124],good:119,got:20,gpg:[19,22],gpgkei:2,grace:[8,124],grant:[35,90],greppabl:119,group:[11,12,14,19,22,27,28,29,30,31,33,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,53,54,55,56,105,106,120,123],groupaddaclkeep:37,groupaddgatekeep:38,groupaddguestaccess:31,groupaddmemb:32,groupaddown:39,groupaddserv:27,groupcreat:105,groupdelaclkeep:40,groupdelegresskei:41,groupdelet:106,groupdelgatekeep:42,groupdelguestaccess:33,groupdelmemb:34,groupdelown:43,groupdelserv:28,groupdestroi:44,groupgenerateegresskei:45,groupgeneratepassword:46,groupinfo:53,grouplist:54,grouplistguestaccess:35,grouplistpassword:55,grouplistserv:56,groupmodifi:47,groupsetserv:29,grouptransmitownership:48,guest:[3,35],harden:19,hardwar:17,hash:[55,75,96],have:[23,72,115],help:[57,120],high:19,home:20,homedir:7,hook:15,host:[50,61,63,68],how:[12,14,17],http:[5,71,123],i:[17,57],idlekilltimeout:0,idlelocktimeout:0,immedi:12,impact:14,imperson:25,inact:102,indic:18,info:[11,59],inform:[12,53,59,91,110],ingress:[0,66,67,71,74,95,100],ingresskeysfrom:0,ingresskeysfromallowoverrid:0,ingressrequirepiv:0,ingresstoegressrul:0,insecur:5,instal:[17,18,19,20,22],instanc:59,instruct:23,integr:15,interact:12,interactivemodeallow:0,interactivemodebydefault:0,interactivemodeproactivemfaen:0,interactivemodeproactivemfaexpir:0,interactivemodetimeout:0,introduct:[12,119,123,124,125],ip:[27,28,56],ish:18,jit:[12,14],json:[16,119],jumphost:18,just:18,kei:[2,3,19,22,41,45,66,67,68,69,73,74,94,95,100,112,124],keyboardinteractiveallow:0,known:68,launch:[16,52],like:52,linger:6,list:[0,2,3,4,5,6,7,8,9,10,13,27,28,29,32,34,35,54,55,56,72,73,74,75,76,92,93,94,95,96,111,112,115,120],locat:11,lock:[17,60,104],log:[0,2,3,4,6,7,8,9,10,11,19,23],log_facil:[2,6,7,9],log_request_respons:5,log_request_response_max_s:5,logdir:10,logfil:[2,4,6,7,9],m:57,machin:[20,52],main:[0,1,6,23],mainten:24,manag:[24,120],manual:[20,60],master:19,max_ag:6,max_serv:5,max_spare_serv:5,maximumegressrsakeys:0,maximumingressrsakeys:0,me:18,mean:17,member:[32,34,120],membership:11,messag:[11,125],meta:57,metadata:[55,75,96],mfa:[12,14],mfapasswordinactivedai:0,mfapasswordmaxdai:0,mfapasswordmindai:0,mfapasswordwarndai:0,mfapostcommand:0,min_serv:5,min_spare_serv:5,minimumegressrsakeys:0,minimumingressrsakeys:0,mitig:14,mode:[12,24],model:125,modifi:[47,99,100],more:[18,120],moshallow:0,moshcommandlin:0,moshtimeoutnetwork:0,moshtimeoutsign:0,mtime_dai:9,mtr:61,multi:12,my:17,nc:62,need:20,network:0,nocontain:16,now:23,ok:18,onli:12,open:[11,58,62],oper:20,option:[0,2,3,4,5,6,7,8,9,10,17,59,84,113],orphan:7,osh:[2,3,4,5,6,7,8,9,10,12,17,51],other:0,our:20,output:[53,59,91],over:17,owner:[39,43,49],ownership:48,packag:20,pair:[45,69],pam:12,pam_faillock:104,pam_tal:104,pam_tally2:104,password:[46,55,70,71,75,77,79,89,96,97,123],passwordallow:0,past:[76,81],payload:119,per:[12,124],period:124,perl:17,person:[84,86,113,114,120,123],pertain:56,ping:[50,63],piv:[8,100,124],pki:17,plgfail:16,plugin:[12,18,26,30,36,49,58,59,84,107,113,121],polici:[0,2,100,124],port:[5,62],possibl:100,practic:119,pre:15,prerequisit:[22,125],present:18,pretti:119,prevent:88,principl:[117,118],print:53,privat:[45,69],product:[17,22],proper:[12,23],proxi:[5,71,123],proxycommand:17,puppet:20,push:[4,19],push_opt:2,push_remot:2,putti:127,queri:123,rc2:23,readonlyslavemod:0,realli:17,realm:[108,109,110,111],realmcreat:108,realmdelet:109,realminfo:110,realmlist:111,reaper:[6,8],recipi:4,recommend:17,record:[11,19],refer:[0,2,3,4,5,6,7,8,9,10,16],relayhost:18,remot:[2,4,10,19,52,62,63,64,65,82],remotecommandescapebydefault:0,remotehostlist:10,remoteus:10,remov:[9,28,33,34,40,41,42,43,67,77,78,86,97,98,114],replac:29,replai:81,reproduc:14,requir:12,restor:22,restrict:[90,101,107],retvalshouldb:16,review:[20,121],revok:101,role:[37,38,39,40,42,43,120],root:[19,20,112],rootlistingresskei:112,rotat:19,rshcmd:10,rsync:[4,64,125],rsync_delay_before_remove_dai:4,rsync_destin:4,rsync_rsh:4,run:[15,16,17,51,61,123],s:[18,27,28,29],sandbox:21,satellit:1,scp:[65,125],script:1,secur:[11,13,118],selfaddingresskei:66,selfaddpersonalaccess:113,selfdelingresskei:67,selfdelpersonalaccess:114,selfforgethostkei:68,selfgenerateegresskei:69,selfgeneratepassword:70,selfgenerateproxypassword:71,selflistaccess:72,selflistegresskei:73,selflistingresskei:74,selflistpassword:75,selflistsess:76,selfmfaresetpassword:77,selfmfaresettotp:78,selfmfasetuppassword:79,selfmfasetuptotp:80,selfplaysess:81,sens:17,sequenti:52,server:[12,17,20,27,28,31,33,35,56,64,65,72,82,84,86,113,114,115,120,121],session:[0,6,17,60,76,81,83,121],set:[121,123],setup:[10,12,15,20,79,80],sever:52,sftp:[82,125],sh:10,show:72,sign:[2,4],signatur:19,signing_kei:[2,4],signing_key_passphras:[2,4],slave:19,snippet:12,so:57,some:[53,59,91,120],somebodi:48,soon:50,specif:[17,23,31,33,35,126],sqlite:11,ssh:[0,12,17,18,19,126],sshclientdebuglevel:0,sshclienthasoption:0,sshd_config:12,sshfp:19,ssl_certif:5,ssl_kei:5,stdin:51,step:[22,121],subset:12,success:16,summari:14,superowneraccount:0,support:[12,23,124,125],sync:[10,19,22],synchron:[10,19],syntax:16,syslog:[10,11,19],syslog_facil:[3,4,8],syslogdescript:0,syslogfacil:0,system:20,tabl:18,tcp:62,tell:18,telnetallow:0,temporari:124,termin:11,test:[15,16],thi:[54,57,59,112],through:[51,64,65,82,123],timelin:14,timeout:[5,10],tool:[15,61],totp:[78,80,98],totpprovid:0,tracerout:61,transfer:[64,65,82],transmit:48,trust:108,ttyrec:[11,19,81],ttyrecadditionalparamet:0,ttyrecfilenameformat:0,ttyrecgroupidoffset:0,ttyrecstealthstdoutpattern:0,tutori:126,type:11,uid:[19,22],under:17,unexpir:102,unfreez:103,unix:[77,79,97],unlock:[83,104],up:[121,123],upgrad:23,us:[12,15,17,21,64,65,71,82,119,127],usag:[18,24,25,27,28,29,31,32,33,34,35,37,38,39,40,41,42,43,44,45,46,47,48,50,51,52,53,54,55,56,57,59,60,61,62,63,64,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,108,109,110,111,112,113,114,115,125],user:[12,25],v3:23,valid:16,valu:[100,119],verbos:4,verifi:16,version:23,view:93,wait:18,warn:11,warnbeforekillsecond:0,warnbeforelocksecond:0,watcher:10,welcom:18,what:[17,18],whether:62,whohasaccessto:115,why:17,without:[15,124],work:20,workflow:[12,123],write:16,yet:18,you:72,your:[20,48,60,66,67,68,69,70,73,74,75,76,77,78,79,80,83,113,114],yourself:120}}) \ No newline at end of file diff --git a/using/api.html b/using/api.html new file mode 100644 index 0000000..fa4c8dd --- /dev/null +++ b/using/api.html @@ -0,0 +1,417 @@ + + + + + + + JSON API — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

JSON API

+ +
+

Introduction

+

The Bastion has a JSON API that can be used to interact with Plugins.

+

Instead of exposing a specific HTTPS port for this API, The Bastion leverages its already exposed protocol, SSH, +to expose its API through it. The rationale is:

+
    +

  • Avoid exposing a new port and a new protocol (HTTPS) to avoid widening the attack surface

    • +

  • Leverage the pre-existing authentication and user isolation mechanisms implemented by The Bastion behind SSH

    • +
+

This API is implemented for all plugins, and can be enabled by the --json* series of options.

+
+

Note

+

Within this page, the bssh bastion alias we usually use through the documentation is replaced by +explicit ssh commands, to emphasize the fact that as we're doing M2M calls, +there would be no terminal involved, hence we shouldn't use the -t SSH option to connect to the bastion +(as is the case with the bssh alias).

+
+

Adding either --json, --json-pretty or --json-greppable to your --osh commands enable +the JSON API output. Here is an example of each one below.

+
+
+

Examples

+
+

Using --json-pretty

+

Let's start with --json-pretty:

+
ssh robot-group@bastion1.example.org -- --osh groupListServers --group mygroup --json-pretty
+╭──ac777d06bec9───────────────────────────────────────────the-bastion-3.12.00───
+│ ▶ list of servers pertaining to the group
+├───────────────────────────────────────────────────────────────────────────────
+│        IP PORT  USER      ACCESS-BY ADDED-BY   ADDED-AT
+│ --------- ---- ----- -------------- -------- ----------
+│ 127.1.2.3   22 (any) mygroup(group)  johndoe 2023-07-31
+│
+│ 1 accesses listed
+
+JSON_START
+{
+   "command" : "groupListServers",
+   "value" : [
+      {
+         "port" : "22",
+         "expiry" : null,
+         "forcePassword" : null,
+         "forceKey" : null,
+         "addedBy" : "johndoe",
+         "userComment" : null,
+         "comment" : null,
+         "user" : null,
+         "ip" : "127.1.2.3",
+         "addedDate" : "2023-07-31 08:56:05",
+         "reverseDns" : null
+      }
+   ],
+   "error_code" : "OK",
+   "error_message" : "OK"
+}
+
+JSON_END
+╰─────────────────────────────────────────────────────────</groupListServers>───
+
+
+

As you see, adding --json-pretty to the command enables output of additional text that can be parsed as JSON. +This option is the most human-readable one, and encloses the JSON output between two anchors, namely +JSON_START and JSON_END. All the text output out of these anchors can be ignored for the JSON API parsing.

+

Here is an example of parsing using simple shell commands:

+
ssh robot-group@bastion1.example.org -- --osh groupListServers --group mygroup --json-pretty --quiet | \
+  awk '/^JSON_END\r?$/ {if(P==1){exit}} { if(P==1){print} } /^JSON_START\r?$/ {P=1}' | jq .
+{
+  "error_code": "OK",
+  "error_message": "OK",
+  "value": [
+    {
+      "userComment": null,
+      "reverseDns": null,
+      "expiry": null,
+      "user": null,
+      "forceKey": null,
+      "addedDate": "2023-07-31 08:56:05",
+      "port": "22",
+      "addedBy": "johndoe",
+      "ip": "127.1.2.3",
+      "forcePassword": null,
+      "comment": null
+    }
+  ],
+  "command": "groupListServers"
+}
+
+
+

Note that we use --quiet, which removes some text that is only useful to humans, and it also disables colors +in the output. In any case, the JSON API output between the anchors never has colors enabled.

+
+
+

Using --json

+

This option uses the same anchors than --json-pretty, but doesn't prettify the JSON, so the output +is more compact:

+
ssh robot-group@bastion1.example.org -- --osh groupListServers --group mygroup --json
+---ac777d06bec9-------------------------------------------the-bastion-3.12.00---
+=> list of servers pertaining to the group
+--------------------------------------------------------------------------------
+~        IP PORT  USER          ACCESS-BY ADDED-BY   ADDED-AT
+~ --------- ---- ----- ------------------ -------- ----------
+~ 127.1.2.3   22 (any)     mygroup(group)  johndoe 2023-07-31
+~
+~ 1 accesses listed
+
+JSON_START
+{"error_code":"OK","error_message":"OK","value":[{"forcePassword":null,"expiry":null,"port":"22","addedBy":"johndoe","ip":"127.1.2.3","userComment":null,"addedDate":"2023-07-31 08:56:05","user":null,"reverseDns":null,"comment":null,"forceKey":null}],"command":"groupListServers"}
+JSON_END
+
+
+

As the anchors are the same, the parsing can be done with the same logic as above:

+
ssh robot-group@bastion1.example.org -- --osh groupListServers --group mygroup --json --quiet | \
+  awk '/^JSON_END\r?$/ {if(P==1){exit}} { if(P==1){print} } /^JSON_START\r?$/ {P=1}' | jq .
+{
+  "error_code": "OK",
+  "error_message": "OK",
+  "value": [
+    {
+      "userComment": null,
+      "reverseDns": null,
+      "expiry": null,
+      "user": null,
+      "forceKey": null,
+      "addedDate": "2023-07-31 08:56:05",
+      "port": "22",
+      "addedBy": "johndoe",
+      "ip": "127.1.2.3",
+      "forcePassword": null,
+      "comment": null
+    }
+  ],
+  "command": "groupListServers"
+}
+
+
+
+
+

Using --json-greppable

+

This is a variant of the --json option, but instead of relying on JSON_START and JSON_END anchors, +which works for both --json and --json-pretty modes, here the JSON output is packed on one line, +starting with the JSON_OUTPUT= anchor. +You may use the option that is the easier for you to parse in your script or calling program.

+
ssh robot-group@bastion1.example.org -- --osh groupListServers --group mygroup --json--greppable
+---ac777d06bec9-------------------------------------------the-bastion-3.12.00---
+=> list of servers pertaining to the group
+--------------------------------------------------------------------------------
+~        IP PORT  USER          ACCESS-BY ADDED-BY   ADDED-AT
+~ --------- ---- ----- ------------------ -------- ----------
+~ 127.1.2.3   22 (any)     mygroup(group)  johndoe 2023-07-31
+~
+~ 1 accesses listed
+
+JSON_OUTPUT={"error_code":"OK","command":"groupListServers","error_message":"OK","value":[{"reverseDns":null,"userComment":null,"user":null,"forceKey":null,"port":"22","addedDate":"2023-07-31 08:56:05","expiry":null,"addedBy":"johndoe","ip":"127.1.2.3","comment":null,"forcePassword":null}]}
+----------------------------------------------------------</groupListServers>---
+
+
+

Here is an example of parsing using simple shell commands:

+
ssh robot-group@bastion1.example.org -- --osh groupListServers --group mygroup --json-greppable --quiet | \
+  grep ^JSON_OUTPUT= | cut -d= -f2- | jq .
+{
+  "error_code": "OK",
+  "error_message": "OK",
+  "value": [
+    {
+      "userComment": null,
+      "reverseDns": null,
+      "expiry": null,
+      "user": null,
+      "forceKey": null,
+      "addedDate": "2023-07-31 08:56:05",
+      "port": "22",
+      "addedBy": "johndoe",
+      "ip": "127.1.2.3",
+      "forcePassword": null,
+      "comment": null
+    }
+  ],
+  "command": "groupListServers"
+}
+
+
+
+
+
+

JSON payload format

+

The JSON payload is always a hash with 4 keys: error_code, error_message, value and command, +as you may have witnessed from the examples above.

+

These keys are detailed below.

+
+

command

+

The associated value is a string, containing the name of the command (plugin) that generated this output.

+
+
+

error_code

+

The associated value is an always-uppercase string. You should look at the prefix of this string to know +whether the command was a success or not. The value is never null and always matches the following regex: +^(OK|KO|ERR)[A-Z0-9_]*$. The possible prefixes are either:

+
    +

  • OK: the command has succeeded

    • +

  • KO: the command did not succeed

    • +

  • ERR: the command encountered an error, more information should be available in the error_message field, +the value field will most likely be null

    • +
+

Examples of such values include: KO_ACCESS_DENIED, OK, OK_NO_CHANGE, ERR_MEMBER_CANNOT_BE_GUEST.

+

You should rely on these error codes in the code using The Bastion's API to take decisions.

+
+
+

error_message

+

The associated value is a string, intended for human reading. It gives more details about the returned error_code, +but is not intended to be parsed by your code, as it may change without notice from version to version. If there is no +specific error_message for a given case, the value will be the same than the one for error_code, hence this +field is guaranteed to always exist and never be null.

+
+
+

value

+

The data associated to the key value is entirely dependent on command, and can be a nested structure of +hashes and/or arrays. This is the actual data payload returned by the command you've invoked. Note that value +can also be null, particularly if the error_code doesn't start with the OK prefix.

+
+
+
+

Good practices

+

If you're intending interaction with The Bastion API, it's a good idea to have accounts dedicated to this, to have +a clear distinction between human SSH usage and automated API calls. Additionally, if your automation will only +use such accounts to call plugins (--osh commands), you might want to create such accounts with the --osh-only +parameter to accountCreate, this guarantees that such accounts will never be able to use The Bastion to connect +to other infrastructures (e.g. using SSH) even if granted to.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/using/basics/access_management.html b/using/basics/access_management.html new file mode 100644 index 0000000..a5ff886 --- /dev/null +++ b/using/basics/access_management.html @@ -0,0 +1,282 @@ + + + + + + + Access management — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Access management

+

There are two ways of managing authorizations on The Bastion, it is extremely important +to understand those two ways because they're complementary.

+
+

Note

+

This section is largely inspired from the blog post about the subject

+
+

The main idea is that delegation is at the core of the system: everybody has their own set of responsibilities, +and potential actions, without having to ask the bastion admin.

+
+

Personal Accesses

+

On the bastion, each account has (at least) one set of personal egress keys. +These beasts are generated when the account is first created. +The personal egress private key sits in the bastion account home. +The account user has no way to see it, or export it out of the bastion, +but they can use it through the bastion's code logic. +The user can retrieve the corresponding public key at any time, using the selfListEgressKeys +command, and install it – or get it installed – on the remote servers they needs to access. +Depending on your use case – and the level of autonomy you want to give to the teams – there are +two ways of managing these personal accesses.

+
+

Decentralized (help yourself)

+

The first way mimics how you would manage accesses if you weren't using an SSH bastion at all. +This is a perfectly valid way to handle accesses on a simple level, without too many users and a limited +number of machines. This allows anyone to grant themselves personal accesses on the bastion, +without having to ask anyone else to do it. It sounds like a security hole, but it's not. +If someone adds themself a personal access to the remote server, it will only work if their +personal egress public key has already been installed on the remote server. +In other words, they either already had access to the remote server to do this – using means other than the bastion – +or somebody who had access to the remote server accepted the addition of their key. +Either way, they cannot magically grant themselves personal access without +the admins of the remote server first permitting their key.

+
+
+

Centralized (ask the IT crowd)

+

Another way to handle this can be to grant a limited number of people, such as security teams, +the right to add personal accesses to others. This way people are less autonomous, but it might be useful +if adding accesses has to be enacted via normalized processes. It also has some nice effects: as a sysadmin, +one of the pros is that you can create 3 separate accounts on the remote machine, and map them to each bastion account +you're adding. This is a good method for achieving end-to-end traceability; including on the remote server; +where you might want to install auditd or similar tools. +It's also doable in the help yourself mode, but it may be harder to enforce.

+

To be clear, this access model doesn't scale so efficiently when we're dealing with whole teams, +or big infrastructures – this is where group-based access comes handy.

+
+
+
+

Group Accesses

+../../_images/groups.png +

A group has three components:

+
    +

  • A list of members (accounts, representing individual people)

    • +

  • At least one set of group egress keys

    • +

  • A list of servers (or more precisely IPs)

    • +
+
+

Servers list

+

The servers list is actually a list of IPs, or IP blocks. They map to your servers, network devices, +or anything else with SSH capability that has an IP (on which the egress group key has been installed). +Technically, this list is actually composed of 3-tuple items: remote user, remote IP (or IP block), remote port. +That which applies to the personal accesses, also applies here: adding a server to the list doesn't magically +give access to it, it is first necessary to install the egress group public key. +Of course, managing the installation of these keys manually quickly becomes impractical, +but you can consider these part of the configuration of the servers, hence they should be managed with whichever +centralized configuration system you already use (Puppet, Chef, Ansible, /bin/cp… wait, no, strike this last one).

+
+
+

Members list

+

The members are people who can connect to any server listed in the group server list. +They'll be using the private egress group key they have access to, as members of said group. +Of course, they have no way to extract this private key for their own use outside of the bastion, +they can only use it through the bastion's code logic.

+

Got a new team member? Just add them as a member of your group, and they instantly get access to all the group servers. +Somebody leaves the company? Just delete their account on the bastion, and all the accesses are instantly gone. +This is the case because all your servers should have incoming SSH sessions limited to your bastions. +This way, any rogue SSH key that would have been added, is no longer of any use.

+
+
+

And some more

+

We've covered the basics of the group-based approach, but as we need a lot of flexibility and delegation, +there is a little more to cover. Remember when I said a group had 3 components? Well, I lied. +A group has more than just members. Additional group roles include:

+
    +

  • Guests

    • +

  • Gatekeepers

    • +

  • Aclkeepers

    • +

  • Owners

    • +
+

All of these are lists of accounts that have a specific role in the group.

+../../_images/group_roles.png +

First, guests. These are a bit like members, but with less privileges: they can connect to remote machines +using the group key, but not to all the machines of the group, only to a subset. +This is useful when somebody outside of the team needs a specific access to a specific server, +potentially for a limited amount of time (as such accesses can be set to expire).

+

Then, gatekeepers. Those guys manage the list of members and guests of the group. +In other terms, they have the right to give the right to get access. Nothing too complicated here. +Then, there are the aclkeepers. As you may have guessed, they manage the list of servers that are +part of the group. If you happen to have some automation managing the provisioning of servers of your infrastructure, +this role could be granted to a robot account whose sole purpose would be to update the servers list on the bastion, +in a completely integrated way with your provisioning. +You can even tag such accounts so that they'll never be able to use SSH through the bastion, +even if somebody grants them by mistake!

+

Last but not least, the owners have the highest privilege level on the group, which means they can manage +the gatekeepers, aclkeepers and owners lists. They are permitted to give the right to give the right to get access. +Moreover, users can accumulate these roles, which means some accounts may be a member +and a gatekeeper at the same time, for example.

+
+
+
+

Global roles

+

Beyond the roles we have just described – which are all scoped to a group – there are two additional roles, +which are scoped to the whole bastion: the superowner and the bastion admin.

+

In a nutshell, a superowner is the implicit owner of all groups present on the bastion. +This comes in handy if the group becomes ownerless, as superowners are able to nominate a brand new owner.

+

The most powerful role is the bastion admin. This role should only be given to a few individuals, +as they can impersonate anyone, and in practice should not be given to somebody who is not already root +on the bastion's operating system itself. Among other things, they manage the configuration of the bastion, +where the superowners are declared.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/using/basics/first_steps.html b/using/basics/first_steps.html new file mode 100644 index 0000000..457e512 --- /dev/null +++ b/using/basics/first_steps.html @@ -0,0 +1,372 @@ + + + + + + + First steps — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

First steps

+
+

Bastion alias

+

You should setup a bastion alias to make it easy to connect to the bastion. +An example of the proper alias to use for your account is given to the bastion administrator +when they creates your account, and is usually something along the lines of:

+
alias bssh='ssh -t myname@the-bastion.example.org --'
+
+
+

Of course, you can modify it as you see fit, for example adding the -i argument to specify the private SSH key +to use to connect to the bastion. You can use any name as the alias, +but it's advised to keep it short, as you'll use it quite often.

+

For the remaining of this documentation, we'll assume your bastion alias is bssh.

+

You can do two categories of things on the bastion:

+
    +

  • Connect to infrastructures through it

    • +

  • Interact with the bastion itself, for example to manage your account, and/or groups, +through so-called PLUGINS aka osh commands

    • +
+
+
+

Plugins

+

We'll start by using the info plugin, to verify that your bastion access works correctly:

+
bssh --osh info
+*------------------------------------------------------------------------------*
+|THIS IS A PRIVATE COMPUTER SYSTEM, UNAUTHORIZED ACCESS IS STRICTLY PROHIBITED.|
+|ALL CONNECTIONS ARE LOGGED. IF YOU ARE NOT AUTHORIZED, DISCONNECT NOW.        |
+*------------------------------------------------------------------------------*
+Enter PIN for 'PIV Card Holder pin (PIV_II)':
+---the-bastion.example.org----------------------------the-bastion-2.99.99-rc9---
+=> information
+--------------------------------------------------------------------------------
+~ You are johndoe
+~ You are a bastion auditor!
+~ Look at you, you are a bastion superowner!
+~ Woosh, you are even a bastion admin!
+~
+~ Your alias to connect to this bastion is:
+~ alias bssh='ssh johndoe@the-bastion.example.org -p 22 -t -- '
+~ Your alias to connect to this bastion with MOSH is:
+~ alias bsshm='mosh --ssh="ssh -p 22 -t" johndoe@the-bastion.example.org -- '
+~
+~ [...]
+~
+~ Here is your excuse for anything not working today:
+~ BOFH excuse #46:
+~ waste water tank overflowed onto computer
+----------------------------------------------------------------------</info>---
+Connection to the-bastion.example.org closed.
+
+
+

Congratulations, you've just used your first command on the bastion!

+

You can get a list of all the plugins you can use by saying:

+
bssh --osh help
+
+
+

The list will depend on your access level on the bastion, as some commands are restricted. +You can have more information about any command by using --help with it:

+
bssh --osh selfAddIngressKey --help
+
+
+

See the PLUGINS section on the left menu, for more information about the plugins.

+

Instead of using --osh to call plugins, you can enter the special interactive mode, by saying:

+
bssh -i
+
+
+

In this mode, you can directly enter commands, and also use auto-completion features with the <TAB> key. +You can start by just typing help, which is the equivalent of saying bssh --osh help. +For security reasons, the interactive mode will disconnect you after a given amount of idle-time.

+
+
+

Setting up access to a server

+
+

Note

+

This section assumes that you've just set up your bastion and your account is the one that has been created +on installation, with all the super-powers included, especially access to the restricted +selfAddPersonalAccess command that we'll use below. +If this is not the case, you'll need first to have a bastion admin grant you this command +through accountGrantCommand

+
+

Let's say that you have a server you want to secure access to, using the bastion. +We'll call it server42.example.org, with IP 198.51.100.42. +To do this, we'll use the selfAddPersonalAccess command.

+

We can use the interactive mode to get the auto-completion features:

+
bssh -i
+Enter PIN for 'PIV Card Holder pin (PIV_II)':
+
+Welcome to bssh interactive mode, type `help' for available commands.
+You can use <tab> and <tab><tab> for autocompletion.
+You'll be disconnected after 60 seconds of inactivity.
+Loading... 88 commands and 341 autocompletion rules loaded.
+
+bssh(master)>
+
+
+

You can enter the first few characters of the command, then use <TAB> to help you complete it, +then use <TAB> again to show you the required arguments. The complete command would be as follows:

+
bssh(master)> selfAddPersonalAccess --host 198.51.100.42 --port 22 --user root
+---the-bastion.example.org----------------------------the-bastion-2.99.99-rc9---
+=> adding private access to a server on your account
+--------------------------------------------------------------------------------
+~ Testing connection to root@198.51.100.42, please wait...
+Warning: Permanently added '198.51.100.42' (ECDSA) to the list of known hosts.
+root@198.51.100.42: Permission denied (publickey).
+~ Note: if you still want to add this access even if it doesn't work, use --force
+~ Couldn't connect to root@198.51.100.42 (ssh returned error 255). Hint: did you add the proper public key to the remote's authorized_keys?
+-----------------------------------------------------</selfAddPersonalAccess>---
+bssh(master)>
+
+
+

You'll notice that it didn't work. This is because first, you need to add your personal egress key to the +remote machine's authorized_keys file. If this seems strange, here is +how it works. +To get your personal egress key, you can use this command:

+
bssh(master)> selfListEgressKeys
+---the-bastion.example.org----------------------------the-bastion-2.99.99-rc9---
+=> the public part of your personal bastion key
+--------------------------------------------------------------------------------
+~ You can copy one of those keys to a remote machine to get access to it through your account
+~ on this bastion, if it is listed in your private access list (check selfListAccesses)
+~
+~ Always include the from="198.51.100.1/32" part when copying the key to a server!
+~
+~ fingerprint: SHA256:rMpoCaYPSfRqmOBFOJvEr5uLqxYjqYtRDgUoqUwH2nA (ED25519-256) [2019/07/11]
+~ keyline follows, please copy the *whole* line:
+from="198.51.100.1/32" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILnY2NQTKsTDxgcaTE6vHVm9FIbud1rJcYQ/4xUyr+DK johndoe@bssh:1562861572
+--------------------------------------------------------</selfListEgressKeys>---
+
+
+

Now that you have it, you can push this public key (the line starting with the from=) to the remote server's +root authorized_keys, i.e. /root/.ssh/authorized_keys. Now, you can add your access properly:

+
bssh(master)> selfAddPersonalAccess --host 198.51.100.42 --port 22 --user root
+---the-bastion.example.org----------------------------the-bastion-2.99.99-rc9---
+=> adding private access to a server on your account
+--------------------------------------------------------------------------------
+~ Testing connection to root@198.51.100.42, please wait...
+Warning: Permanently added '198.51.100.42' (ECDSA) to the list of known hosts.
+~ Access to root@198.51.100.42:22 successfully added
+-----------------------------------------------------</selfAddPersonalAccess>---
+bssh(master)>
+
+
+

All seems in order! Can we see this access we just created?

+
bssh(master)> selfListAccesses
+---the-bastion.example.org----------------------------the-bastion-2.99.99-rc9---
+=> your access list
+--------------------------------------------------------------------------------
+~ Dear johndoe, you have access to the following servers:
+~ IP               PORT     USER    ACCESS-BY   ADDED-BY      ADDED-AT
+~ 198.51.100.42      22     root    personal     johndoe    2020-05-01
+-----------------------------------------------------</selfListAccesses>---
+bssh(master)>
+
+
+
+
+

Connecting to a server and reviewing the session

+

Good! Let's try to connect now!

+
bssh(master)> ssh root@198.51.100.42
+~ Welcome to the-bastion, johndoe, your last login was 00:13:37 ago (Fri 2020-08-28 13:07:43 UTC) from 192.0.2.11(proxy-11.example.org)
+
+proxy-11.example.org:40610 => johndoe@the-bastion.example.org:22 => root@server42.example.org:22 ...
+ allowed ... log on(/home/johndoe/ttyrec/198.51.100.42/2020-08-28.13-07-45.497020.fb00e1957b22.johndoe.root.198.51.100.42.22.ttyrec)
+
+ will try the following accesses you have:
+  - personal access with ED25519-256 key SHA256:rMpoCaYPSfRqmOBFOJvEr5uLqxYjqYtRDgUoqUwH2nA [2019/07/11]
+
+Connecting...
+
+root@server42:~# id
+uid=0(root) gid=0(root) groups=0(root),2(bin)
+root@server42:~#
+
+
+

We're now connected to server42, and can do our work as usual. Note that to connect to server42, one can directly use:

+
bssh root@198.51.100.42
+
+
+

Where bssh is the bastion alias we've just set up above, no need to enter interactive mode first of course.

+

When we're done with server42, let's see if everything was correctly recorded:

+
bssh(master)> selfListSessions --type ssh --detailed
+---the-bastion.example.org---------------------the-bastion-2.99.99-rc9.2-ovh1---
+=> your past sessions list
+--------------------------------------------------------------------------------
+~ The list of your 100 past sessions follows:
+~
+f4cca44a848e [2020/08/26@09:28:57 - 2020/08/26@09:29:57 (         60.0)] type ssh from 192.0.2.11:33450(proxy-11.example.org) via johndoe@198.51.100.1:22 to root@198.51.100.42:22(server42.example.org) returned 0
+----------------------------------------------------------</selfListSessions>---
+
+
+

The first column is the unique identifier of the connection (or osh command). +Let's see what we did exactly during this session:

+
bssh(master)> selfPlaySession --id f4cca44a848e
+---the-bastion.example.org---------------------the-bastion-2.99.99-rc9.2-ovh1---
+=> replay a past session
+--------------------------------------------------------------------------------
+~       ID: f4cca44a848e
+~  Started: 2020/08/26 09:28:57
+~    Ended: 2020/08/26 09:29:57
+~ Duration: 0d+00:01:00.382820
+~     Type: ssh
+~     From: 192.0.2.11:33450 (proxy-11.example.org)
+~      Via: johndoe@198.51.100.1:22
+~       To: root@198.51.100.42:22 (server42.example.org)
+~  RetCode: 0
+~
+~ Press '+' to play faster
+~ Press '-' to play slower
+~ Press '1' to restore normal playing speed
+~
+~ When you're ready to replay session 9f352fd4b85c, press ENTER.
+~ Starting from the next line, the Total Recall begins. Press CTRL+C to jolt awake.
+
+
+

Now that you've connected to your first server, using a personal access, +you may want to learn more about the Access management, or directly dive into the PLUGINS on the left menu.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/using/basics/index.html b/using/basics/index.html new file mode 100644 index 0000000..b367e57 --- /dev/null +++ b/using/basics/index.html @@ -0,0 +1,182 @@ + + + + + + + The basics — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

The basics

+

This section explains the basics you need to know to work with the bastion. +It's advised to go through all the subsections.

+

We make the assumption here that you already have a bastion account:

+
    +

  • either you're one of the admins who just installed it, or

    • +

  • one of the admins created an account for you, using accountCreate

    • +
+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/using/http_proxy.html b/using/http_proxy.html new file mode 100644 index 0000000..67039ec --- /dev/null +++ b/using/http_proxy.html @@ -0,0 +1,380 @@ + + + + + + + HTTPS Proxy — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

HTTPS Proxy

+ +
+

Introduction

+

In addition to securing your SSH accesses, by splitting the authentication part (ingress connection) +and the authorization part (egress connection), The Bastion can do a similar job for HTTPS connections.

+

Note that there is an overhead (depending on your hardware setup) of several hundreds of milliseconds +for each query-response trip, due to the fact that multiple processes are spawned for each query, +to ensure proper security containment to the calling account's system user. +It's probably a bad idea to use on a multi-million queries/day workload, +or if each added millisecond to the query-response trip impacts the QoS of your service.

+

The primary use is for network devices, that happen to have more and more HTTPS APIs in addition +to the usual conf terminal available through SSH. As the same commands are usually available from +HTTPS and SSH on these devices, it would be too bad to secure the access to SSH through the bastion, +but leave direct access to their HTTPS API!

+
+
+

Query workflow

+

The workflow is similar to the one used by SSH, e.g. two distinct connections (ingress and egress), +with the egress connection using credentials stored on the bastion:

+
    +

  • A client makes an HTTP request to the proxy, with the following information embedded in:

    +
      +

    • The type of request (GET or POST)

      • +

    • The complete URI, including the host of the remote HTTPS server it would like to send the request to

      • +

    • Potential body data for POST requests

      • +

    • Credentials to authenticate to the proxy on the ingress connection, namely the +bastion account name and its proxy password (set by selfGenerateProxyPassword)

      • +

    • User name to use to authenticate on the remote HTTPS server (for the egress connection)

      • +
    +
    • +

  • The bastion checks the provided credentials to authenticate the request against a known account (authentication part)

    • +

  • The bastion verifies whether the just-authenticated account has access rights to connect to the remote server +as the specified remote user (authorization part)

    • +

  • The bastion uses the (group or personal) credentials stored on the bastion, +to passthrough the HTTP request to the remote server, as the specified remote user

    • +

  • The bastion forwards the response to the client

    • +
+
+
+

Setting up the HTTPS Proxy

+

You should enable the HTTPS Proxy daemon, and configure it. +Please check the osh-http-proxy.conf for more information.

+
+
+

Running a query through the proxy

+
+

First try

+

Once the proxy is running, we can try to query it:

+
curl https://bastion1.example.org:8443/
+No authentication provided, and authentication is mandatory
+
+
+

Of course, the proxy only accepts to work when one is properly authenticated to it. +To do this, one should have an account on the bastion, and use the selfGenerateProxyPassword +command so that a new ingress password is set for their account. They'll then be able to authenticate to the proxy +using the HTTP basic-auth method, and try to send a request to a remote server. +To keep a high compatibility with HTTP clients and libraries that can be used on the ingress side, +all the additional data required by the bastion to properly authenticate, authorize and passthrough the request +is encoded in the user part of the widely supported HTTP Authorize header (basic-auth). +The password part corresponds to the password we've generated just above.

+

The format of the user part is as follows:

+
BASTION_ACCOUNT@REMOTE_USER@REMOTE_HOST%REMOTE_PORT
+
+
+

The %REMOTE_PORT part is optional, and defaults to 443 if omitted. +For example, to send a GET /info request to the remote network device named router12.example.org on +the default port 443, using the remote account monitoring, through the bastion1.example.org bastion, +having the HTTPS Proxy listening on its port 8443 and a bastion account robot-mon, one can use curl:

+
curl -u robot-mon@monitoring@router12.example.org https://bastion1.example.org:8443/info
+Enter host password for user 'robot-mon@monitoring@router12.example.org':
+This account doesn't have access to this user@host tuple (Access denied for robot-mon to monitoring@router12.example.org:443)
+
+
+

A password will be prompted: the password generated by selfGenerateProxyPassword should be entered. +Remember: this is to authenticate yourself to the bastion (ingress connection), then the bastion will authenticate +itself to the remote machine (egress connection), using credentials stored on the bastion, +that your account must have access to.

+

In the above case, we entered the password correctly, but our account doesn't have access to +the requested host monitoring@router12.example.org. This is what we need to do now.

+
+
+

Access declaration

+

The access check is the same than the one done for SSH accesses, which means that oneself +can have access to a remote host either through a personal access or +a group access.

+

To get granted access to a remote device, through a personal access, either +the selfAddPersonalAccess or the accountAddPersonalAccess shall +be used (both are restricted commands) such as:

+
bssh --osh accountAddPersonalAccess --host router12.example.org --port 443 --user monitoring --force
+
+
+

Note the use of --force to skip the SSH connection test, which is useless in our case.

+

To use a group access instead, one of the aclkeepers of the group +should use groupAddServer, such as:

+
bssh --osh groupAddServer --group netdevices --host router12.example.org --port 443 --user monitoring --force
+
+
+
+
+

Egress password

+
+

For personal accesses

+

If access to a remote device is granted to you through a personal access (using either the selfAddPersonalAccess +or accountAddPersonalAccess commands), you must first generate a new set of credentials that will be stored +on your bastion account, for egress connections. This is the equivalent of your personal egress keys for SSH, +but in that case it's a password that will be used to authenticate using basic-auth to the remote server. +You can generate this password using the selfGeneratePassword command:

+
bssh --osh selfGeneratePassword --do-it
+*------------------------------------------------------------------------------*
+|THIS IS A PRIVATE COMPUTER SYSTEM, UNAUTHORIZED ACCESS IS STRICTLY PROHIBITED.|
+|ALL CONNECTIONS ARE LOGGED. IF YOU ARE NOT AUTHORIZED, DISCONNECT NOW.        |
+*------------------------------------------------------------------------------*
+╭──bastion1.example.org───────────────────────────────the-bastion-3.03.99-rc1───
+│ ▶ generating a new egress password for your account
+├───────────────────────────────────────────────────────────────────────────────
+│ Generated a new password of length 16 for your account, robot-mon, hashes follow:
+│ md5crypt: $1$G0fo$2DH2OJQJ9bMgo5fUUuPeK.
+│ sha256crypt: $5$2xd1aGuD$ze7px3olXdjWthSrdnzelm6avzT2kszx/voXms8/V00
+│ sha512crypt: $6$udw2UNLs$tQ1p7ZYraOT4Woh1ZCGJNf.UAIh09nXPBf4ejpRurOY/fJUs6Dgh1WdkpY4pdCvKMQrPeetB42bNTSzIwJyGi1
+│ This new password will now be used by default.
+╰─────────────────────────────────────────────────────</selfGeneratePassword>───
+
+
+

As you can see, the password is stored on your bastion account, and is not printed: only its hashes are. +With this information, the corresponding remote account can be provisioned on the device (usually, a network device). +In our above example, an account named monitoring would have to be created on the remote device, +using one of these hashes. Prefer to use the most secure hashing algorithm supported by the remote device.

+

To get your password (hash) list, you can use selfListPasswords:

+
bssh --osh selfListPasswords
+*------------------------------------------------------------------------------*
+|THIS IS A PRIVATE COMPUTER SYSTEM, UNAUTHORIZED ACCESS IS STRICTLY PROHIBITED.|
+|ALL CONNECTIONS ARE LOGGED. IF YOU ARE NOT AUTHORIZED, DISCONNECT NOW.        |
+*------------------------------------------------------------------------------*
+╭──bastion1.example.org───────────────────────────────the-bastion-3.03.99-rc1───
+│ ▶ list your egress passwords
+├───────────────────────────────────────────────────────────────────────────────
+│ Current password created at Tue Jun 22 15:42:10 2021 by robot-mon
+│ ... md5crypt: $1$G0fo$2DH2OJQJ9bMgo5fUUuPeK.
+│ ... sha256crypt: $5$2xd1aGuD$ze7px3olXdjWthSrdnzelm6avzT2kszx/voXms8/V00
+│ ... sha512crypt: $6$udw2UNLs$tQ1p7ZYraOT4Woh1ZCGJNf.UAIh09nXPBf4ejpRurOY/fJUs6Dgh1WdkpY4pdCvKMQrPeetB42bNTSzIwJyGi1
+│
+│ Fallback password 1 created at Wed Jun  2 08:00:01 2021 by robot-mon
+│ ... md5crypt: $1$qF0M$2.rbRRGs66aPiEpc/SqGv/
+│ ... sha256crypt: $5$E9qkC7D6$SG8BB.nXvwU0dB0Bq9S/sF5pDidLwSIDKCv95qNWhX0
+│ ... sha512crypt: $6$druGNgSk$bzVHSvux/OOE2ZhDpabFekQU3GTsiKS7Yl/lLmb9gIAmjnFfR6gj7GzOniK2jdLtEcB/hQlhcx9TDgj5zHhVd.
+│
+╰────────────────────────────────────────────────────────</selfListPasswords>───
+
+
+

If the selfGeneratePassword command is used several times, the newly generated password will always override +the previous one. Still, all the previous passwords are kept (archived) for good measure, and can be restored +manually by a bastion admin. These passwords are named Fallback passwords in the output of selfListPasswords.

+
+
+

For group accesses

+

If the access to the remote device is given through a group, then the group's own credentials will be used. +To this effect, one of the group owners should use the groupGeneratePassword command:

+
bssh --osh groupGeneratePassword --group netdevices --do-it
+╭──bastion1.example.org───────────────────────────────the-bastion-3.03.99-rc1───
+│ ▶ generating a new egress password for the group
+├───────────────────────────────────────────────────────────────────────────────
+│ Generated a new password of length 16 for group netdevices, hashes follow:
+│ md5crypt: $1$9sb2$X8/pPBSLfQ0ddBGR/bzsT1
+│ sha256crypt: $5$o6Jr8w0X$yQfLuX17tUwE1jfhhAX//vsn6KpXU5jUd7SCNbkYNH.
+│ sha512crypt: $6$gyxMyjao$YNhZJPXZa4r838XKg2tfvvoV/Dtm5HKsyKt18BnvFfT.y.hZuSXRX9GhM4mA0hUsO9f0UBisO/WiK3vF/9qsL1
+│ This new password will now be used by default.
+╰────────────────────────────────────────────────────</groupGeneratePassword>───
+
+
+

As with the personal egress passwords, the password is stored on the bastion only, and is not printed: +only its hashes are. With this information, the corresponding remote account can be provisioned +on the device (usually, a network device). +In our above example, an account named monitoring would have to be created on the remote device, +using one of these hashes. Prefer to use the most secure hashing algorithm supported by the remote device.

+

To get the group's password (hash) list, one can use the groupListPasswords command:

+
bssh --osh groupListPasswords --group netdevices
+*------------------------------------------------------------------------------*
+|THIS IS A PRIVATE COMPUTER SYSTEM, UNAUTHORIZED ACCESS IS STRICTLY PROHIBITED.|
+|ALL CONNECTIONS ARE LOGGED. IF YOU ARE NOT AUTHORIZED, DISCONNECT NOW.        |
+*------------------------------------------------------------------------------*
+╭──bastion1.example.org───────────────────────────────the-bastion-3.03.99-rc1───
+│ ▶ list the egress passwords of the group
+├───────────────────────────────────────────────────────────────────────────────
+│ Current password created at Tue Jun 29 10:21:38 2021 by slesimpl
+│ ... md5crypt: $1$9sb2$X8/pPBSLfQ0ddBGR/bzsT1
+│ ... sha256crypt: $5$o6Jr8w0X$yQfLuX17tUwE1jfhhAX//vsn6KpXU5jUd7SCNbkYNH.
+│ ... sha512crypt: $6$gyxMyjao$YNhZJPXZa4r838XKg2tfvvoV/Dtm5HKsyKt18BnvFfT.y.hZuSXRX9GhM4mA0hUsO9f0UBisO/WiK3vF/9qsL1
+╰───────────────────────────────────────────────────────</groupListPasswords>───
+
+
+

If the groupGeneratePassword command is used several times, the newly generated password will always +override the previous one. Still, all the previous passwords are kept (archived) for good measure, +and can be restored manually by a bastion admin. +These passwords are named Fallback passwords in the output of groupListPasswords.

+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/using/piv.html b/using/piv.html new file mode 100644 index 0000000..3f8af55 --- /dev/null +++ b/using/piv.html @@ -0,0 +1,326 @@ + + + + + + + PIV keys support — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

PIV keys support

+ +
+

Introduction

+

The Bastion supports enabling a policy forcing accounts SSH ingress keys to originate from a known hardware token, +ensuring that the private SSH key is only stored on this hardware token, and not on the filesystem.

+

Currently, only Yubico keys implementing PIV can be verified this way. In that case, each individual hardware token +has a builtin Certificate Authority, signed by a well-known Yubico certificate, hence proving that the hardware token +is known and legit.

+

This builtin CA, in turn, emits an attestation certificate each time a new PIV key is generated on the hardware token, +hence proving that the bikey (private and public) has been generated by this individual hardware token. +Other metadata is included in the attestation, such as the firmware version, the serial number of the token, +the TouchPolicy and PinPolicy. Note that you may decide to overwrite the builtin CA by a one of your own, +possibly signed by a CA of your company. This would ensure not only that the SSH key is provided by the device, +but also that the device has been provided by your company.

+

Please refer to +the Yubico PIV attestation page and +the Yubico PIV tool page +for more information.

+
+
+

Without a policy

+

If you want to support PIV keys without making those mandatory, you don't have anything to do: +those keys are just regular RSA/ECDSA keys and they just work with The Bastion. +In that case, after having properly configured your hardware token with a key in slot 9a, +you can just use selfAddIngressKey to add the key to your bastion account, and call it a day. +As a quick guidance, on a Yubikey you can usually generate a key in the proper slot this way, +after you've setup a management key:

+
yubico-piv-tool --key=YOUR_MGMT_KEY --action generate --pin-policy always --touch-policy never --slot 9a -o -
+
+
+

Now, if you want the bastion to be aware that this key is from a hardware token, you shall use the --piv option +to selfAddIngressKey. This won't do anything special per-se, except storing +the certificates information, and showing the details of the PIV key in command outputs +such as selfListIngressKeys. +Note however that if in the future you enable the PIV enforcing policy either on your account or globally, +this key will be considered valid, contrary to all the keys added without the --piv option, +even if these keys happen to be PIV ones. To add a key with the --piv option, you'll need the SSH public key +as usual, but also the attestation certificate and the key certificate. +Step by step details on how to get those are out of the scope of this document, +but again as a quick guidance, on a Yubikey you can usually get those this way:

+
yubico-piv-tool --action=read-certificate --slot=9a --key-format=SSH
+yubico-piv-tool --action=attest --slot=9a
+yubico-piv-tool --action=read-certificate --slot=f9
+
+
+

When you'll have added your key, you'll see a few more details than usual:

+
bssh --osh selfAddIngressKey --piv
+Enter PIN for 'PIV Card Holder pin (PIV_II)':
+---the-bastion.example.org--------------------------------the-bastion-3.01.03---
+=> add a new public key to your account
+--------------------------------------------------------------------------------
+~ Please paste the SSH key you want to add. This bastion supports the following algorithms:
+~ ED25519: strongness[#####] speed[#####], use `ssh-keygen -t ed25519' to generate one
+~ ECDSA  : strongness[####.] speed[#####], use `ssh-keygen -t ecdsa -b 521' to generate one
+~ RSA    : strongness[###..] speed[#....], use `ssh-keygen -t rsa -b 4096' to generate one
+~
+~ In any case, don't save it without a passphrase.
+~ You can prepend your key with a from="IP1,IP2,..." as this bastion policy allows ingress keys "from" override by users
+ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCyAMtxGT/RvzBZXiYlrCswZMruRtoBtONrVJTZ3Cj5ZpjaZyCRjQ/ETzZXXbvu9KiBsZyhVb/5H9F7CSGi+D5BlcRAKrT9P8MsT7BHWU14GhJddhHDy4rMnXapE93oxbnQIjQT34ozvTKlb0qOoR/SlT14LllvQS6ajaXB7Fm4bAJG/gYGXHEs2nmZn37Rll6vvpZ4ExM29UrqU3hAjYO0Ha+kL5G8Tr+fOhV/5ZmzNsYigdW7Ft7Co4Tpld9D0PqVhDPK7F1zHIFUXunFsewGtB3IQxLdLGDaCMzrRi11V6q/pBzN/75YsW6npRdOzJKjnwxG19lTtVCmCY3EPRFz
+~
+~ You have requested to add a PIV-enabled SSH key.
+~ Please paste the PIV attestation certificate of your hardware key in PEM format.
+~ This snippet should start with '-----BEGIN CERTIFICATE-----' and end with '-----END CERTIFICATE-----':
+~
+-----BEGIN CERTIFICATE-----
+MIIDIDCCAgigAwIBAgIQAajpKeFbM+X1Yfk8GaH9dzANBgkqhkiG9w0BAQsFADAh
+MR8wHQYDVQQDDBZZdWJpY28gUElWIEF0dGVzdGF0aW9uMCAXDTE2MDMxNDAwMDAw
+MFoYDzIwNTIwNDE3MDAwMDAwWjAlMSMwIQYDVQQDDBpZdWJpS2V5IFBJViBBdHRl
+c3RhdGlvbiA5YTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBALIAy3EZ
+P9G/MFleJiWsKzBkyu5G2gG042tUlNncKPlmmNpnIJGND8RPNlddu+70qIGxnKFV
+v/kf0XsJIaL4PkGVxEAqtP0/wyxPsEdZTXgaEl12EcPLisyddqkT3ejFudAiNBPf
+ijO9MqVvSo6hH9KVPXguWW9BLpqNpcHsWbhsAkb+BgZccSzaeZmfftGWXq++lngT
+Ezb1SupTeECNg7Qdr6QvkbxOv586FX/lmbM2xiKB1bsW3sKjhOmV30PQ+pWEM8rs
+XXMcgVRe6cWx7Aa0HchDEt0sYNoIzOtGLXVXqr+kHM3/vlixbqelF07MkqOfDEbX
+2VO1UKYJjcQ9EXMCAwEAAaNOMEwwEQYKKwYBBAGCxAoDAwQDBQIEMBQGCisGAQQB
+gsQKAwcEBgIEALeG1jAQBgorBgEEAYLECgMIBAIDATAPBgorBgEEAYLECgMJBAEB
+MA0GCSqGSIb3DQEBCwUAA4IBAQAq9O6H02KRvSmBYsz23r6cNTNS/fr5lSPYMHz/
+fX+D5B1thKKGstsfZVzoopwIjj86cIWpCYuNfEje+a5HrELL8ClV88JutJR2Nihs
+NxU3BbsSUqnwi2rQHcmtHJcC8rjfDzpYDlW1yR+SxVenbVxuRy0v8sbleHSPYaXG
+EhjupEAuhq7n0TjZMF1X7KElx9FZZM9HeuxUJvzV7XWiUgA4Zm05+4/zKW01n2kt
++aMaQk7T1oiE0oOK51wJX6J80GzF51pM00oPlh4iDvnnNXYN2KvkNuNwPoceDDE/
+8K23ZfJyTN5nibk13UbxEWSHMUue1zcnFp0KdhqxbJYSS/9q
+-----END CERTIFICATE-----
+~
+~ Thanks, now please paste the PIV key certificate of your generated key in PEM format.
+~ This snippet should also start with '-----BEGIN CERTIFICATE-----' and end with '-----END CERTIFICATE-----':
+~
+-----BEGIN CERTIFICATE-----
+MIIC5jCCAc6gAwIBAgIJAKT/dqaxohbiMA0GCSqGSIb3DQEBCwUAMCsxKTAnBgNV
+BAMMIFl1YmljbyBQSVYgUm9vdCBDQSBTZXJpYWwgMjYzNzUxMCAXDTE2MDMxNDAw
+MDAwMFoYDzIwNTIwNDE3MDAwMDAwWjAhMR8wHQYDVQQDDBZZdWJpY28gUElWIEF0
+dGVzdGF0aW9uMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwDhP3YUI
+yLWSjseIKNzMscqCdicslrdkxPgMoK8Ocxu0err4yvFXiSZZL32BTZYLD8N7Y+d1
+cww6VVsFYdwn01Kc6YLrwM5FIN/msXkGTPdPVhVeqNMHh4QyYrYixwWaTbDCGoQD
+axVlifVmPS02Mvm8NDjC17X3LhsV1OiS/wOScsI8HHGgQXQIQEDMnt6cwZ83QK73
+7Wuu5uhSzT3jVOz28Rnij1p/8PcVWcGKWCPVYNbCmCdcm/sQeJB8y5aERDaePIIZ
+v9axnDT0DnUO7aDpzXA7i7XPbrkiSBEp7RCqXGs5cBqGCbq//xGh+/AGtCCV/sQM
+nTjl0d2k2Q8XTwIDAQABoxUwEzARBgorBgEEAYLECgMDBAMFAgQwDQYJKoZIhvcN
+AQELBQADggEBAHCnp3k5kQaBwYmR9nUHKGY1dgCvhJUlX2SAyY2fUeaMuURcRRlW
+BFw6CvLAjvSs5Dy3O6JWDmk+1WFZo0UMr15WZFiS5Fpy0M+GWvBCRP3YmbSw+J2t
+kyWypCIIu7cMtLpRYkL5SAlWmUCAz8dZPk5FLPpeqmxgQnRoSSe67IXiv3bNyPA1
+3NoXI2xw0hWQU1+85tfTxoTxOiAzY8UpAT2GggtSmCwO3sHsHJUYXRyCf8e6jtJL
+OFBx/uz+VJoRH7hUVOY+sbP5JJ83dRrWZkS57Hf3q0LOtbn27vM+fmL0y7z4vgDo
+DedmrmsbPtsRc3t7RWoqCa80Iq1jPvdm5gw=
+-----END CERTIFICATE-----
+~
+~ Public key successfully added:
+~ info: ADDED_BY=jdoe USING=selfAddIngressKey UNIQID=2993de2bb014 TIMESTAMP=1609427402 DATETIME=2020-12-31T15:10:02 VERSION=3.01.03
+~ PIV: TouchPolicy=Never, PinPolicy=Always, SerialNo=12345678, Firmware=5.2.4
+~ fingerprint: SHA256:8B0T6174KUPL1iTSyC0UpnDOvuaCgyKpu8zo9rb2lco (RSA-2048) [2020/12/17]
+---------------------------------------------------------</selfAddIngressKey>---
+
+
+

As you can see, we added the public key as usual but were also asked for the two certificates. +On the bastion answer, right before the fingerprint of the key, we have a line starting with PIV:, +with some metadata extracted from the certificate.

+
+
+

Per-account policy

+

If you want to force several accounts to only use certified PIV keys, you can set the option per-account +using the accountPIV command, see its documentation page for all the possible options. +The main takeaways are:

+
    +

  • If you want an account to only have PIV keys, set the enforce policy for this account

    • +

  • If you want an account to never require PIV keys, even if the global policy would require it, +set the never policy (useful for accounts used by automated workflows)

    • +
+
+
+

Global policy

+

If you want to apply a policy bastion-wide, please refer to the ingressRequirePIV option. +This policy can still be overridden per-account if needed, see above.

+
+
+

Temporary grace period

+

If you enable the PIV policy globally or on several accounts, you'll soon find out that sometimes people forget +or lose their PIV-enabled hardware tokens, effectively locking them out of the bastion. +There is a temporary grace period feature you can use to handle such cases nicely:

+
bssh --osh accountPIV --account lechuck --policy grace --ttl 48h
+---the-bastion.example.org--------------------------------the-bastion-3.01.03---
+=> modify the PIV policy of an account
+--------------------------------------------------------------------------------
+~ Changing account configuration...
+
+~ PIV grace up to 2d+00:00:00 (Wed 2021-01-13 09:22:29 UTC) has been set for this account
+~ Applying change to keys...
+
+~ Non-PIV account's ingress keys, if any, have been restored
+----------------------------------------------------------------</accountPIV>---
+
+
+

What happens here is that, for a duration of 48 hours, this account will behave as if no PIV policy was enforced: +non-PIV keys are allowed again. If this account had non-PIV keys before its policy was set to enforce, +those keys are even restored (can be viewed using selfListIngressKeys as usual), +so that they can easily connect again. However, after the grace period expires, their policy will go back to +what it was previously, and all the non-PIV keys will be disabled again. +This event is logged, so you can easily link this event from your SIEM to a potential ticket to your Helpdesk +for a hardware key replacement, or such.

+

This mechanism allows some flexibility (avoiding sending people back home just because they forgot their hardware key), +while still enforcing a high-level security policy with the proper processes in place.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/using/sftp_scp_rsync.html b/using/sftp_scp_rsync.html new file mode 100644 index 0000000..f4a9f99 --- /dev/null +++ b/using/sftp_scp_rsync.html @@ -0,0 +1,273 @@ + + + + + + + SFTP, SCP & RSYNC support — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

SFTP, SCP & RSYNC support

+ +
+

Introduction

+

The Bastion's main goal is to secure ssh connections. +However, one might also want to use sftp, scp or rsync through it.

+

Its use is supported through the scp, sftp and +rsync bastion plugins, and documented as part of all the plugins. +This additional documentation section gives some examples and outlines some common configuration errors.

+
+
+

Prerequisites

+
+

SFTP & SCP

+

The use of SFTP or SCP through the bastion requires an SFTP or SCP program that supports the -S option, +and a shell to run the wrapper. This is the case on all operating systems using OpenSSH such as Linux or *BSD.

+

If you're running under Microsoft Windows, you might want to setup either a Linux VM, or a WSL (Windows Subsystem +for Linux) environment, to have the OpenSSH version of scp or sftp and a working POSIX-style shell.

+

Note that it won't work with Windows GUI apps, because there's no way to specify a wrapper (through -S), +and no shell. For example, it won't work under WinSCP.

+
+
+

RSYNC

+

The use of RSYNC through the bastion only requires rsync to be installed locally and remotely, as is the +case for usage without the bastion.

+
+
+
+

Basic usage

+

Please check the scp, sftp and rsync +documentation to see how to use these.

+
+
+

Access model

+
+

Note

+

Currently, to be able to use SFTP, SCP or RSYNC with a remote server, +you first need to have a declared SSH access to it. +This might change in a future version.

+
+
+

Error message 1

+

This is briefly explained in the scp/doc:/plugins/open/sftp/rsync +documentation, but having access rights to SSH to a machine is not enough to have the right to SCP to or from it, +or use SFTP/RSYNC on it. +If you have the following error, then this is the problem you're having:

+
Sorry, you seem to have access through ssh and through scp but by different and distinct means (distinct keys).
+The intersection between your rights for ssh and for scp needs to be at least one.
+
+
+

When this happens, it means that you have at least one declared SSH access to this machine (through one or +several groups, or through personal accesses). You also have at least one declared SCP/SFTP/RSYNC access to it. +However both accesses are declared through different means, and more precisely different SSH keys. For example:

+
    +

  • You are a member of a group having this machine on one hand, and you have a declared SCP/SFTP/RSYNC access to this machine +using a personal access on the other hand. For SSH, the group key would be used, but for SCP/SFTP, your personal key +would be used. However, for technical reasons (that might be lifted in a future version), your SSH and SCP/SFTP/RSYNC access +must be declared with the same key, so in other words, using the same access mean (same group, or personal access).

    • +

  • You are a member of group A having this machine, but SCP/SFTP/RSYNC access is declared in group B. +In that case, as previously, as two different keys are used, this won't work.

    • +
+

To declare an SCP/SFTP/RSYNC access, in addition to a preexisting SSH access, you should use either:

+ +

In both cases, where you would use the --user option to the command, to specify the remote user to use for +the SSH access being declared, you should replace it by either --protocol scpdown, --protocol scpup, +--protocol sftp or --protocol rsync, +to specify that you're about to add an SCP/SFTP/RSYNC access (and not a bare SSH one), and which direction you want +to allow in the case of SCP.

+

For SCP, you can allow both directions by using the command first with --protocol scpdown, +then with --protocol scpup. +Note that for SFTP and RYSNC, you can't specify a direction, due to how these protocols work: you either have +SFTP/RSYNC access (hence being able to upload and download files), or you don't.

+

For example, this is a valid command to add SFTP access to a machine which is part of a group:

+
bssh --osh groupAddServer --group mygroup --host scpserver.example.org --port 22 --protocol sftp
+
+
+
+
+

Error message 2

+

If you have the following message:

+
Sorry, but you don't seem to have access to HOST:IP
+
+
+

Then it means that you don't even have SSH access to this machine. In that case, somebody should grant you access, +either by adding you to a group having this machine (groupAddMember) or by adding +this machine to your personal accesses (accountAddPersonalAccess or +selfAddPersonalAccess).

+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/using/specific_ssh_clients_tutorials/index.html b/using/specific_ssh_clients_tutorials/index.html new file mode 100644 index 0000000..461bece --- /dev/null +++ b/using/specific_ssh_clients_tutorials/index.html @@ -0,0 +1,156 @@ + + + + + + + Specific SSH clients tutorials — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Specific SSH clients tutorials

+

This section has a few howtos about using The Bastion with some specific SSH clients, +mostly ones having a GUI, as the rest of the documentation assumes usage of the +more widespread SSH CLI.

+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/using/specific_ssh_clients_tutorials/putty.html b/using/specific_ssh_clients_tutorials/putty.html new file mode 100644 index 0000000..4f5fc8f --- /dev/null +++ b/using/specific_ssh_clients_tutorials/putty.html @@ -0,0 +1,189 @@ + + + + + + + Using PuTTY with The Bastion — The Bastion 3.16.99-rc2 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Using PuTTY with The Bastion

+

First, you'll need to generate a pair of SSH keys. To this end, use the PuTTY companion tool: PuTTYgen.

+

Before hitting Generate to generate a new key pair, ensure that EdDSA is selected, with the Ed25519 curve. +You'll have to move your mouse a bit to feed the pseudo-random number generator.

+Main window of PuTTYgen +

Once the key has been generated, you'll have to input a passphrase that will protect your key. +Ensure this passphrase is sufficiently hard to guess, but ensure you'll not forget it! +Once you've entered your passphrase twice, it should look like this:

+Main window of PuTTYgen once a key has been generated +

You can now hit Save private key and choose a file name. +Also save the corresponding public key next to it by hitting Save public key, +but don't close PuTTYgen yet.

+

The public key you've just saved, which is also displayed at the top of the PuTTYgen window, +starting by ssd-ed25519 AAAA... is the public key you'll need to give to The Bastion when +creating your account there, so you can copy/paste it when The Bastion asks you for a key:

+Creating an account on The Bastion +

Now, you can close PuTTYgen (as you've saved the private and public keys in their respective +files, you'll be able to use them later), and open PuTTY itself:

+Main window of PuTTY +

To create the proper connection settings, set your bastion host name (or IP) and port in the +window above, and leave the connection type to SSH.

+

Then, navigate to Connection > SSH > Auth > Credentials, and use Browse... to set the +location of the private key you've generated with PuTTYgen. Ensure you use the private +key, not the public key: the private key usually ends in .ppk, as shown below:

+Credentials options section of PuTTY window +

Then, navigate back to Session, and save the session settings under any name you wish, +so that the next time you open PuTTY, you'll be able to load these settings back:

+Saving the settings in PuTTY +

Then, you can click Open to establish the connection. On the first connection attempt, you'll +be prompted with this dialog box:

+Unknown hostkey dialog box +

This is because PuTTY never connected to the bastion before, and asks you to verify the +bastion's host public key. This is expected on the first connection, so you can click Accept.

+

You'll then be prompted for your login, which is the account name you've created on the bastion, +associated with your public key:

+Waiting for the user login +

You'll then need to type the passphrase protecting your private key, so PuTTY can use it:

+Waiting for the private key passphrase +

Once done, the bastion should authenticate you, and drop you in interactive mode:

+ +

You can now use The Bastion!

+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file