Skip to content
This repository has been archived by the owner on Feb 15, 2024. It is now read-only.

Latest commit

 

History

History
204 lines (179 loc) · 45.3 KB

configure.md

File metadata and controls

204 lines (179 loc) · 45.3 KB

brick: Configuring brick

Table of contents

Precedence

The priority order is:

  1. Command line flags (highest priority)
  2. Environment variables
  3. Configuration file
  4. Default settings (lowest priority)

The intent is to support a feathered layering of configuration settings; if, for example, a configuration file provides nearly all settings that you want, specify just the settings that you wish to override via command-line flags (or environment variables) and use the configuration file for the other settings.

Command-line Arguments

  • Flags marked as required must be set via CLI flag or within a TOML-formatted configuration file.
  • Flags not marked as required are for settings where a useful default is already defined.
Option Required Default Repeat Possible Description
h, help No false No h, help Show Help text along with the list of supported flags.
config-file No empty string No valid path to a file Fully-qualified path to a configuration file consulted for settings not already provided via CLI flags or environment variables.
ignore-lookup-errors No false No true, false Whether application should continue if attempts to lookup existing disabled or ignored status for a username or IP Address fail. This is needed if you do not pre-create files used by this application ahead of time. WARNING: Because this can mask errors, you should probably only use it briefly when this application is first deployed, then later disable the setting once all files are in place.
port No 8000 No valid TCP port number TCP port that this application should listen on for incoming HTTP requests. Tip: Use an unreserved port between 1024:49151 (inclusive) for the best results.
ip-address No localhost No valid fqdn, local name or IP Address Local IP Address that this application should listen on for incoming HTTP requests.
trusted-ip-addresses No all No one or many valid fqdn or IP Addresses One or many single IP Addresses which are trusted for payload submission. If this is defined, all other sender IPs are ignored. If this is not defined, payloads are accepted from all IP Addresses not otherwise rejected by local/remote firewall rules.
log-level No info No fatal, error, warn, info, debug Log message priority filter. Log messages with a lower level are ignored.
log-output No stdout No stdout, stderr Log messages are written to this output target.
log-format No text No cli, json, logfmt, text, discard Use the specified apex/log package "handler" to output log messages in that handler's format.
disabled-users-file No /var/cache/brick/users.brick-disabled.txt No valid path to a file Fully-qualified path to the "disabled users" file
disabled-users-file-perms No 0o644 No valid permissions in octal format Permissions (in octal) applied to newly created "disabled users" file. NOTE: EZproxy will need to be able to read this file.
disabled-users-entry-suffix No ::deny No valid EZproxy condition/action String that is appended after every username added to the disabled users file in order to deny login access.
reported-users-log-file No /var/log/brick/users.brick-reported.log No valid path to a file Fully-qualified path to the log file where this application should log user disable request events for fail2ban to ingest.
reported-users-log-file-perms No 0o644 No valid permissions in octal format Permissions (in octal) applied to newly created "reported users" log file. NOTE: fail2ban will need to be able to read this file.
ignored-users-file No /usr/local/etc/brick/users.brick-ignored.txt No valid path to a file Fully-qualified path to the file containing a list of user accounts which should not be disabled and whose IP Address reported in the same alert should not be banned by this application. Leading and trailing whitespace per line is ignored.
ignored-ips-file No /usr/local/etc/brick/ips.brick-ignored.txt No valid path to a file Fully-qualified path to the file containing a list of individual IP Addresses which should not be disabled and whose user account reported in the same alert should not be disabled by this application. Leading and trailing whitespace per line is ignored.
teams-webhook-url Maybe empty string No valid webhook url The Webhook URL provided by a preconfigured Connector. If specified, this application will attempt to send applicable notifications to the Microsoft Teams channel associated with the webhook URL.
teams-notify-rate-limit No 5 No number of seconds as a whole number The number of seconds to wait between Microsoft Teams notification attempts. This rate limit is intended to help prevent unintentional abuse of remote services and is applied regardless of whether the last notification attempt was initially successful or required one or more retry attempts.
teams-notify-retry-delay No 5 No number of seconds as a whole number The number of seconds to wait between Microsoft Teams message retry delivery attempts.
teams-notify-retries No 2 No valid whole number The number of attempts that this application will make to deliver a Microsoft Teams message before giving up and discarding the message.
email-server-name Maybe empty string No valid fqdn or IP Address The SMTP server that this application should connect to for email message delivery. Specify localhost if testing or sending mail via a local SMTP server instance. Examples include running a Postfix null client which sends all mail to a relayhost on the local network or a Maildev Docker container for development purposes.
email-server-port No 25 No valid TCP port number The TCP port that this application should connect to for email message delivery. The default is usually port 25, but may be different depending on your environment (e.g., 1025 if using the Maildev container).
email-recipient-addresses Maybe empty list No valid email addresses The comma or space-separated list of email addresses that should receive all outgoing email notifications from this application.
email-sender-address Maybe empty string No valid email address The email address used as the sender for all outgoing email notifications from this application.
email-client-identity No fqdn, local hostname or brick (fallback) No valid fqdn, local host or application name The hostname provided with the HELO or EHLO greeting to the SMTP server. Be aware that many SMTP servers expect this value to be a valid FQDN with forward and reverse DNS records. If left blank, this value is generated by retrieving the local system's fully-qualified domain name, the local hostname or as a fallback, the hard-coded default value.
email-notify-rate-limit No 3 No number of seconds as a whole number The number of seconds to wait between email notification attempts. This rate limit is intended to help prevent unintentional abuse of remote services and is applied regardless of whether the last notification attempt was initially successful or required one or more retry attempts.
email-notify-retry-delay No 2 No number of seconds as a whole number The number of seconds to wait between email message retry delivery attempts.
email-notify-retries No 2 No valid whole number The number of attempts that this application will make to deliver an email message before giving up and discarding the message.
ezproxy-executable-path No /usr/local/ezproxy/ezproxy No valid path to a file The fully-qualified path to the EZproxy executable/binary. This executable is usually named 'ezproxy' and is set to start at system boot. The fully-qualified path to this executable is required for session termination.
ezproxy-active-file-path No /usr/local/ezproxy/ezproxy.hst No valid path to a file The fully-qualified path to the Active Users and Hosts 'state' file used by EZproxy (and this application) to track current sessions and hosts managed by EZproxy.
ezproxy-audit-file-dir-path No /usr/local/ezproxy/audit No valid path to a directory The path to the directory containing the EZproxy audit files. The assumption is made that all files within are based on YYYYMMDD.txt pattern. Any other file pattern found within this path is ignored (e.g, .zip or .tar or whatnot for a one-off quick backup made by a sysadmin of a specific file).
ezproxy-search-retries No 7 No valid whole number The number of retries allowed for the audit log and active files before the application accepts that 'cannot find matching session IDs for specific user' is really the truth of it and not a race condition between this application and the EZproxy application (e.g., EZproxy accepts a login, but delays writing the state information for about 2 seconds to keep from hammering the storage device).
ezproxy-search-delay No 1 No number of seconds as a whole number The delay in seconds between searches of the audit log or active file for a specified username. This is an attempt to work around race conditions between EZproxy updating its state file (which has been observed to have a delay of up to several seconds) and this application reading the active file. This delay is applied to the initial search and each subsequent retried search for the provided username.
ezproxy-terminate-sessions No false No true, false Whether session termination support is enabled. If false, session termination will not be initiated by this application, though current session IDs found as part of preparing for termination will still be logged for troubleshooting purposes. If setting (or leaving) this as false, the assumption is that either no handling of reported users is desired (other than perhaps logging and notification) or that a tool such as fail2ban is used to monitor the reported users log file and temporarily block the source IP in order to force session timeout.

Environment Variables

If set, environment variables override settings provided by a configuration file. If used, command-line arguments override the equivalent environment variables listed below. See the Command-line Arguments table for more information.

Flag Name Environment Variable Name Notes Example (mostly using default values)
config-file BRICK_CONFIG_FILE BRICK_CONFIG_FILE="/usr/local/etc/brick/config.toml"
ignore-lookup-errors BRICK_IGNORE_LOOKUP_ERRORS BRICK_IGNORE_LOOKUP_ERRORS="false"
port BRICK_LOCAL_TCP_PORT BRICK_LOCAL_TCP_PORT="8000"
ip-address BRICK_LOCAL_IP_ADDRESS BRICK_LOCAL_IP_ADDRESS="localhost"
trusted-ip-addresses BRICK_TRUSTED_IP_ADDRESSES BRICK_TRUSTED_IP_ADDRESSES="127.0.0.1"
log-level BRICK_LOG_LEVEL BRICK_LOG_LEVEL="info"
log-output BRICK_LOG_OUTPUT BRICK_LOG_OUTPUT="stdout"
log-format BRICK_LOG_FORMAT BRICK_LOG_FORMAT="text"
disabled-users-file BRICK_DISABLED_USERS_FILE BRICK_DISABLED_USERS_FILE="/var/cache/brick/users.brick-disabled.txt"
disabled-users-file-perms BRICK_DISABLED_USERS_FILE_PERMISSIONS BRICK_DISABLED_USERS_FILE_PERMISSIONS="0o644"
disabled-users-entry-suffix BRICK_DISABLED_USERS_ENTRY_SUFFIX BRICK_DISABLED_USERS_ENTRY_SUFFIX="::deny"
reported-users-log-file BRICK_REPORTED_USERS_LOG_FILE BRICK_REPORTED_USERS_LOG_FILE="/var/log/brick/users.brick-reported.log"
reported-users-log-file-perms BRICK_REPORTED_USERS_LOG_FILE_PERMISSIONS BRICK_REPORTED_USERS_LOG_FILE_PERMISSIONS="0o644"
ignored-users-file BRICK_IGNORED_USERS_FILE BRICK_IGNORED_USERS_FILE="/usr/local/etc/brick/users.brick-ignored.txt"
ignored-ips-file BRICK_IGNORED_IP_ADDRESSES_FILE BRICK_IGNORED_IP_ADDRESSES_FILE="/usr/local/etc/brick/ips.brick-ignored.txt"
teams-webhook-url BRICK_MSTEAMS_WEBHOOK_URL BRICK_MSTEAMS_WEBHOOK_URL="https://outlook.office.com/webhook/a1269812-6d10-44b1-abc5-b84f93580ba0@9e7b80c7-d1eb-4b52-8582-76f921e416d9/IncomingWebhook/3fdd6767bae44ac58e5995547d66a4e4/f332c8d9-3397-4ac5-957b-b8e3fc465a8c"
teams-notify-rate-limit BRICK_MSTEAMS_WEBHOOK_RATE_LIMIT BRICK_MSTEAMS_WEBHOOK_RATE_LIMIT="5"
teams-notify-retry-delay BRICK_MSTEAMS_WEBHOOK_RETRY_DELAY BRICK_MSTEAMS_WEBHOOK_RETRY_DELAY="5"
teams-notify-retries BRICK_MSTEAMS_WEBHOOK_RETRIES BRICK_MSTEAMS_WEBHOOK_RETRIES="2"
email-server-name BRICK_EMAIL_SERVER_NAME BRICK_EMAIL_SERVER_NAME="smtp.example.org"
email-server-port BRICK_EMAIL_SERVER_PORT BRICK_EMAIL_SERVER_PORT="25"
email-recipient-addresses BRICK_EMAIL_RECIPIENT_ADDRESSES BRICK_EMAIL_RECIPIENT_ADDRESSES="[email protected],[email protected],[email protected]"
email-sender-address BRICK_EMAIL_SENDER_ADDRESS BRICK_EMAIL_SENDER_ADDRESS="[email protected]"
email-client-identity BRICK_EMAIL_CLIENT_IDENTITY BRICK_EMAIL_CLIENT_IDENTITY="eres-proxy.example.org"
email-notify-rate-limit BRICK_EMAIL_NOTIFY_RATE_LIMIT BRICK_EMAIL_NOTIFY_RATE_LIMIT="3"
email-notify-retry-delay BRICK_EMAIL_NOTIFY_RETRY_DELAY BRICK_EMAIL_NOTIFY_RETRY_DELAY="2"
email-notify-retries BRICK_EMAIL_NOTIFY_RETRIES BRICK_EMAIL_NOTIFY_RETRIES="2"
ezproxy-executable-path BRICK_EZPROXY_EXECUTABLE_PATH BRICK_EZPROXY_EXECUTABLE_PATH="/usr/local/ezproxy/ezproxy"
ezproxy-active-file-path BRICK_EZPROXY_ACTIVE_FILE_PATH BRICK_EZPROXY_ACTIVE_FILE_PATH="/usr/local/ezproxy/ezproxy.hst"
ezproxy-audit-file-dir-path BRICK_EZPROXY_AUDIT_FILE_DIR_PATH BRICK_EZPROXY_AUDIT_FILE_DIR_PATH="/usr/local/ezproxy/audit"
ezproxy-search-retries BRICK_EZPROXY_SEARCH_RETRIES BRICK_EZPROXY_SEARCH_RETRIES="7"
ezproxy-search-delay BRICK_EZPROXY_SEARCH_DELAY BRICK_EZPROXY_SEARCH_DELAY="1"
ezproxy-terminate-sessions BRICK_EZPROXY_TERMINATE_SESSIONS BRICK_EZPROXY_TERMINATE_SESSIONS="false"

Configuration File

Configuration file settings have the lowest priority and are overridden by settings specified in other configuration sources, except for default values. See the Command-line Arguments table for more information, including the available values for the listed configuration settings.

Flag Name Config file Setting Name Section Name Notes
ignore-lookup-errors ignore_lookup_errors
port local_tcp_port network
ip-address local_ip_address network
trusted-ip-addresses trusted_ip_addresses network Multi-line array
log-level level logging
log-format format logging
log-output output logging
disabled-users-file file_path disabledusers
disabled-users-file-perms file_permissions disabledusers
disabled-users-entry-suffix entry_suffix disabledusers
reported-users-log-file file_path reportedusers
reported-users-log-file-perms file_permissions reportedusers
ignored-users-file file_path ignoredusers
ignored-ips-file file_path ignoredipaddresses
teams-webhook-url webhook_url msteams
teams-notify-rate-limit rate_limit msteams
teams-notify-retry-delay retry_delay msteams
teams-notify-retries retries msteams
email-server-name server email
email-server-port port email
email-recipient-addresses recipient_addresses email Multi-line array
email-sender-address sender_address email
email-client-identity client_identity email
email-notify-rate-limit rate_limit email
email-notify-retry-delay retry_delay email
email-notify-retries retries email
ezproxy-executable-path executable_path ezproxy
ezproxy-active-file-path active_file_path ezproxy
ezproxy-audit-file-dir-path audit_file_dir_path ezproxy
ezproxy-search-retries search_retries ezproxy
ezproxy-search-delay search_delay ezproxy
ezproxy-terminate-sessions terminate_sessions ezproxy

The contrib/brick/config.example.toml file is provided as a starting point for your own config.toml configuration file. The default values provided by this configuration file should lineup with the default application values if not specified.

Once reviewed and potentially adjusted, your copy of the config.toml file can be placed in a location of your choosing and referenced using the --config-file flag. See the Command-line arguments sections for usage details.

Worth noting

  • Notifications are disabled unless required values are provided

    Notification Type Required Value
    Microsoft Teams webhook URL
    Email remote SMTP server (FQDN or IP Address)
    Email sender address
    Email recipient address(es)

  • For best results, limit your choice of TCP port to an unprivileged user port between 1024 and 49151

  • Log format names map directly to the Handlers provided by the apex/log package. Their descriptions are copied from the official README and provided below for reference:

    Log Format ("Handler") Description
    cli human-friendly CLI output
    json provides log output in JSON format
    logfmt plain-text logfmt output
    text human-friendly colored output
    discard discards all logs

  • Microsoft Teams webhook URLs