Configuration File Details
By default Root the Box looks for a configuration file in ./files/rootthebox.cfg if none exists, a default configuration is used. To write the default configuration to disk run the command rootthebox.py --save. This command can also be used to save any additional command line options to the config file. For example rootthebox.py --save --logging=debug will write the logging setting into the config file. Command line arguments always take precedence over settings stored in the configuration file.
Integer [1 - 65535]
The Web server is bound to this listen port, default is 8888 but you'll most likely want to change this for production deployments. Keep in mind that websockets will need to connect-back to this port too, so take care if you're planning to deploy Root the Box behind a reverse proxy.
String
Attach to which interface. 0.0.0.0 implies all available.
Integer [minutes]
The number of minutes each session can be alive without activity. Default: 2880 (48 hours)
String
Set origin to your IP/hostname with a ws:// or wss:// websocket prefix, for example if your server's address is 192.168.1.1 and you're running the application using http on port 8888, this setting should be ws://192.168.1.1:8888. If you're hosting it externally or through a reverse proxy, you'll want to set it to that address - Example: wss://rootthebox.com. This value is what websocket connections will be validated against so it's important to get it right!
String
Default theme .css file, these are located in static/css/themes/.
Boolean
Enable/disable SSL server, you'll need to manually setup an HTTP/302 to HTTPS if you want it.
String
Certificate file path (e.g. ./foo.crt)
String
Key file path (e.g. ./bar.key)
Boolean
When x-headers is set to True, the application will honor the real IP address provided by a load balancer in the X-Real-Ip or X-Forwarded-For HTTP header.
NOTE: This can affect the admin IP address security restrictions; if you enable this setting it is important that clients cannot directly send requests to the application, or they can manually add an arbitrary X-Forwarded-For header.
List of Strings ['IP Address', 'IPAddress2']
Comma separated list of IPs that can access the administrative web interface, for example: admin_ips = ['127.0.0.1', '192.168.0.25', '10.34.0.2']. By default only 127.0.0.1 is allowed to access the admin interface. Use empty list to allow all ip addresses.
String
url to receive webhook callbacks when certain game actions occur, such as flag capture. See Webhooks
String
The mail server host. Used for sending password reset emails. Consider also setting require_email=True, otherwise the player may not set an email address.
Integer [1 - 65535]
The mail server port, default is 587.
String
The username / email account for the mail server.
String
The password for the email account.
String
The sender address for the email, the FROM address. Sometimes this will be overwritten with the account email by the provider.
Boolean
Start the application in debugging mode.
Boolean
Start the game automatically
String
The directory to store avatar files. Default "./files/avatars"
String
The directory to store shared files. Default "./files/shares"
String
The directory to store flag attachment files. Default "./files/flag_attachments"
String
The directory to store source code market files. Default "./files/source_code_market"
Boolean
When use_box_materials_dir is enabled, a Game Materials folder named to match the Box will be automatically linked on the Box.
String
The directory to store applications, docs, and other materials for the game. Default "./files/game_materials"
Boolean
Force the browser to download game materials with known mime types (instead of just viewing them). Default is True.
String
Force the application to use this locale instead of the browser's locale (e.g. "es_LA"). Language files are in the ./locale directory. Default local is "en_US".
List of Dict
Adds links to the Tools and Upgrades menu. This should be structured as a List of Dictionaries. "name" and "url" are required items in the dictionary, target is optional and will default to "_blank". Default: [{"name": "CyberChef", "url": "/cyberchef/", "target": "_blank"}] Example: [{"name": "Cheat Sheets", "url": "https://pen-testing.sans.org/resources/downloads"}, {"name": "Best Video", "url": "https://www.youtube.com/watch?v=oHg5SJYRHA0", "target": "_self"}]
String
The memcached host (comma separated if multiple hosts). Define non-standard port in hostname:port format.
Used for SASL authentication
Used for SASL authentication
Boolean
Enable/disable the use of ReCAPTCHA for registration, login, and updating user bank account passwords.
String
Recaptcha v2 key; get one at https://www.google.com/recaptcha/.
String [mysql | postgresql | sqlite]
The determines the database type, Root the Box supports mysql, postgresql, or sqlite; defaults to mysql if an invalid dialect is used.
String
This is the name of the database the application should connect to. If SQLite is used, this will be the filename of the database.
String
The database hostname.
Integer [1 - 65535]
The database tcp port
String
The database user, leave blank or set to RUNTIME if you want to prompt for credentials when the application starts, this keeps sensitive db credentials out of plain-text config files, and is recommended for production. This setting is not used for SQLite databases.
String
The database user's password, leave blank or set to RUNTIME if you want to prompt for credentials when the application starts, this keeps sensitive db credentials out of plain-text config files, and is recommended for production. This setting is not used for SQLite databases.
Boolean
Set this to True to log SQL queries made by the ORM, these queries may contain sensitive information! Enable only when you need to debug problems. Very verbose when enabled.
String
URL for the game's Slack/Discord/RocketChat/... chat messaging. Adding a url to this string will create a menu icon for chat, which will open into a new browser tab.
String
Admin account for the game's RocketChat server. This allows integration with the RocketChat API to automatically create user accounts, private team channels, and allow messages to be sent to the chat through RTB
String
Admin account password for the game's RocketChat server. This allows integration with the RocketChat API to automatically create user accounts, private team channels, and allow messages to be sent to the chat through RTB
String
The game name which appears in Web UI. This can also be configured in the administrative interface.
String
Optional version control for keeping track of challenge changes
String
The image displayed on the welcome page.
String
The tagline displayed on the welcome page. Default "A Game of Hackers"
String / HTML
This will be inserted in the page footer on the right side of the page. Useful for adding an organization name / link.
False / String [URL]
If set to a string, players will be asked to accept the privacy policy (the URL points to) upon registration and a link to the privacy policy will be inserted into the footer.
Boolean
Require a registration tokens when creating an account, registration tokens are created in the administrative interface, and must be distributed manually to players. Enable this if you need to control the number of accounts players can create. This can also be configured in the administrative interface.
Boolean
Require a email address when the player creates an account. Default is True - Disable this if you want to allow users to register without providing an email address.
Boolean
Allow users to create their own teams, if this is disabled an administrator must create teams for users to join. This can also be configured in the administrative interface when Team Play is Enabled.
Integer [0 < ]
The maximum number of players which can join any one team. This can also be configured in the administrative interface when Team Play is Enabled.
Boolean
Enabling this feature will set the game and scoreboard up for team competitive play (Team Mode). If this option is disabled, the game is set up for individual competitive play (Player Mode). This can also be configured in the administrative interface.
Boolean
When in individual competitive play (Player Mode), disabling this feature will tell the game to use the playername on the scoreboard, instead of the player's handle. Default is True to use the handle.
Boolean
Enabling this feature will display the player MVP scoreboard. Any player that has contributed points to the team will be displayed. If this option is disabled, the MVP Scoreboard will be hidden. This can also be configured in the administrative interface when Team Play is Enabled.
Integer
Sets the max number of players to display in the MVP Scoreboard when Teams are in use. Default is to display the top 10 players in the MVP list.
Boolean
Enabling this feature will display a flag button on the question after the player successfully captures the flag so that they can see the token. If this option is disabled, no flag button is displayed.
Boolean
Enabling this feature will allow players to share code (pastebin) and files in-game. Disabling this feature will remove these options from the Tools Menu. This can also be configured in the administrative interface when Team Play is Enabled.
Boolean
Enabling this feature will display the number of hints taken on the scoreboard by a team or player. Useful when hints are free. A lower hint count is used for sorting when scores or flags are equal. Disabling this option will remove the hint count from the scoreboard. This can also be configured in the administrative interface.
Boolean
Enabling this feature will send flag and level unlock notifications to all players in the game. Disabling this option will limit those notifications to team members. This can also be configured in the administrative interface.
Boolean
Enabling this feature will group the Missions by the Corporation and then Levels. Default is False, which is to group the Missions by the Level and include the Corporation in the Box title.
Integer
Restrict players user password to this length. This can also be configured in the administrative interface.
Boolean
Enabling this feature will set the game to use a money based scoring system. If this option is disabled, the game uses a points based scoring system. This can also be configured in the administrative interface.
Integer [0 < ]
The number of chars a user can have for their "bank password". This can also be configured in the administrative interface when Banking is Enabled.
Boolean
Enable/disable botnet the features. This can also be configured in the administrative interface.
String
Botnet database path. Default: "files/botnet.db"
Integer [0 < ]
Reward amount for each bot per interval. This can also be configured in the administrative interface when Botnets are Enabled.
Integer [milliseconds]
Award botnets every so many milliseconds.
Boolean
Enable/disable use of the black market unlock features, this includes the Federal Reserve, SWAT, and the Source Code Market. This can also be configured in the administrative interface.
Integer [0 < ]
This is the amount a player must pay to upgrade their bank password's hashing algorithm; each subsequent purchase is also increased by this amount. This can also be configured in the administrative interface when Black Market is Enabled.
Integer
This is the amount a player must pay to 'SWAT' another player's account. Subsequent SWATs of the same player are also increased by this amount each time. This can also be configured in the administrative interface when Black Market is Enabled.
Integer
The starting money for a new team when using banking. This can also be configured in the administrative interface when Banking is Enabled.
Boolean
Whitelist the IPs bots can connect from, enable this if you know all of the IPs of your boxes ahead of time and want additional restrictions on where bots can connect from.
Boolean
Enabling this feature will set the game to follow the storyline of Morris, an employer that sends 'secure communique' and assigns missions. Designed primarily for use with the Banking System. Disabling this option will skip the storyline and give the player an instant capture message. This can also be configured in the administrative interface.
String
This selection determines the visibility of the scoreboard menu and pages. It will take three strings "public", "players", or "admins". The scoreboard can be visible to all visitors (public), to authenticated users (players), or only to administrators (admins).
Boolean
Default is False. This setting is intended to improve performance on large scale games, where many users are regularly refreshing the scoreboard. When the scoreboard is updated, RootTheBox will normally run a gamestate update, but this should be unnecessary. Normally there is no harm doing the update - it just gives another opportunity to keep the cache fresh. However on larger games, query times increase and the update can become excessive and reduce performance. Setting scoreboard_lazy_update to True will skip the gamestate update on scoreboard refresh.
Boolean
Enabling this feature will decrease the reward for a flag based on the number of captures. If this option is disabled, the flag value remains consistent as other players capture it. This can also be configured in the administrative interface.
String
Options: decay_future or decay_all. This selection determines the method by which dynamic scoring is applied. decay_future will decrease the flag value for future captures - this method rewards speed of capture. Each capture decreases the value for the next capture. decay_all will decrease the flag value for past and future team captures - this method rewards difficulty. The more a flag is captured, the less it is worth, with that value applying to all players that have captured the flag. This can also be configured in the administrative interface when Dynamic Scoring is Enabled.
Integer [0-100]
When dynamic_flag_value is True, decrease flag reward by this percent per capture. This can also be configured in the administrative interface when Dynamic Scoring is Enabled.
Integer
When dynamic_flag_value is True, this value indicates the minimum value a flag is worth. This can also be configured in the administrative interface when Dynamic Scoring is Enabled.
Boolean
Enabling this feature will apply a penalty for incorrect capture attempts. The penalty is an instant deduction from the score, not a decrease in the flag value. If this option is disabled, there is no cost for submitting incorrect flags. This can also be configured in the administrative interface.
Integer
Penalize the score by this percent of the flag value for each incorrect attempt (applied after dynamic scoring if enabled). Maximum Penalty is determined as (stop - start) * cost. This can also be configured in the administrative interface when Incorrect Penalty (penalize_flag_value) is Enabled.
Integer
When to start applying the penalty. For example, you may want the first incorrect attempt to be free, but penalize subsequent attempts. 1 = deduct on & after 1st attempt 2 = deduct on & after 2nd attempt and so on ... Maximum Penalty is determined as
(stop - start) * cost. This can also be configured in the administrative interface when Incorrect Penalty (penalize_flag_value) is Enabled.
Integer
When to stop applying the penalty. For example, you may want to only penalize a certain total of the flags value and allow any further attempts to be free, thus allowing all flags to have some value. 4 = stop on & after 4th attempt 5 = stop on & after 5th attempt and so on ... Maximum Penalty is determined as
(stop - start) * cost. This can also be configured in the administrative interface when Incorrect Penalty (penalize_flag_value) is Enabled.
String
The default css theme
Boolean
Allowed the user to change their CSS theme.
String
This selection determines the method by which the scoreboard is primarily ranked. When the primary ranking is equal, other values are used bases on this selection: 1. points/money ▲, hints ▼, flags ▲ 2. flags ▲, points/money ▲, hints ▼ This can also be configured in the administrative interface.
Integer [0-4096]
This is the the limit of characters allowed for a pastebin post. This can also be configured in the administrative interface when Team Sharing is Enabled.
Integer [milliseconds]
Take game snapshots for history graphs every so many milliseconds, this data is used to generate the history graphs on the scoreboard.
List
Add administrator users, multiples supported (' ') --add_admin="handle [email protected] passwordpassword123" Generates admins from a comma-delimited list of strings, formatted as seen in the example here.
List
Generate teams by name ('My team','Another team') --generate_team="My Team", "Their Team", "Another Team" Generates teams from a comma-delimited list of names
Integer
Number of teams to generate (team 1, team 2, etc) --generate_teams=N Generates N numbered teams. e.g. "Team 1", "Team 2" ...
Boolean
Configures the option to automatically ban brute-force attempts
Integer
Sets the threshold for the automatic ban
