diff --git a/docs/content/reference/server-configuration.md b/docs/content/reference/server-configuration.md index f3c02dad899..60f1373e29b 100644 --- a/docs/content/reference/server-configuration.md +++ b/docs/content/reference/server-configuration.md @@ -1,52 +1,202 @@ --- title: "Server configuration" -draft: true -pre: ' ' +draft: false +description: "Reference material for the server_config.json file" +pre: " " --- +{{< table_of_contents >}} -## Configuring the Monkey Island +## Configuration -The Monkey Island Server is configured through the `server_config.json` file. + -{{% notice info %}} -Refer to the [setup guides](../../setup/) to learn how to use -the `server_config.json` file for each deployment. -{{% /notice %}} +| Property | Type | Required | Nullable | +| :----------------------------------- | :-------- | :------- | :------------- | +| [data\_dir](#data_dir) | `string` | Optional | cannot be null | +| [log\_level](#log_level) | `string` | Optional | cannot be null | +| [mongodb](#mongodb) | `object` | Optional | cannot be null | +| [ssl\_certificate](#ssl_certificate) | `object` | Optional | cannot be null | +| [island\_port](#island_port) | `integer` | Optional | cannot be null | -### Creating a configuration file +### data\_dir + +The directory where the Island will store runtime artifacts. + +`data_dir` + +* is optional + +* Type: `string` + +* cannot be null + +#### data\_dir Constraints + +The value of this string must be a valid path. + +#### data\_dir Default Value + +The default value for Windows is: -Here's an example `server_config.json` with all options specified: ```json -{ - "island_port": 443, - "log_level": "DEBUG", - "ssl_certificate": { - "ssl_certificate_file": "", - "ssl_certificate_key_file": "" - }, - "mongodb": { - "start_mongodb": true - }, - "data_dir": "/monkey_island_data" -} +"%AppData%\\monkey_island" ``` -Only relevant options can be specified, for example: +The default value for Linux is: + ```json -{ - "ssl_certificate": { - "ssl_certificate_file": "", - "ssl_certificate_key_file": "" - } -} +"$HOME/.monkey_island" +``` + +### log\_level + +The log level for the Island's logger. + +`log_level` + +* is optional + +* Type: `string` + +* cannot be null + +#### log\_level Default Value + +The default value is: + +```json +"INFO" +``` + +### mongodb + +The MongoDB configuration for the Island server. + +`mongodb` + +* is optional + +* Type: `object` + +* cannot be null + +#### start\_mongodb + +If enabled, the MongoDB server will be started automatically with the Island. + +`start_mongodb` + +* is optional + +* Type: `boolean` + +* cannot be null + +**start\_mongodb Default Value** + +The default value is: + +```json +true +``` + +### ssl\_certificate + +The SSL certificates configuration for the Island server. + +`ssl_certificate` + +* is optional + +* Type: `object` + +* cannot be null + +#### ssl\_certificate\_file + +The path to the SSL certificate file that the Island server will use. + +`ssl_certificate_file` + +* is optional + +* Type: `string` + +* cannot be null + +**ssl\_certificate\_file Constraints** + +The value of this string must be a valid path. + +**ssl\_certificate\_file Default Value** + +The default value is: + +```json +"\\monkey_island\\cc\\server.crt" +``` + +#### ssl\_certificate\_key\_file + +The path to the SSL certificate key file that the Island server will use. + +`ssl_certificate_key_file` + +* is optional + +* Type: `string` + +* cannot be null + +**ssl\_certificate\_key\_file Constraints** + +The value of this string must be a valid path. + +**ssl\_certificate\_key\_file Default Value** + +The default value is: + +```json +"\\monkey_island\\cc\\server.key" ``` -### Configuration options +### island\_port + +The port on which the Island server should listen. + +`island_port` + +* is optional -See setup instructions for your operating system to understand how to apply these. +* Type: `integer` - - `island_port` - Port used by the Island C&C server. Default is `443`. - - `log_level` - can be set to `"DEBUG"`(verbose), `"INFO"`(less verbose) or `"ERROR"`(silent, except errors). - - `ssl_certificate` - contains paths for files, required to run the Island Server with custom certificate. - - `data_dir` - path to a writeable directory where the Island will store the database and other files. - - `mongodb` - options for MongoDB. Should not be changed unless you want to run your own instance of MongoDB. +* cannot be null + +#### island\_port Default Value + +The default value is: + +```json +443 +``` + +### `server_config.json` example + +``` +{ + "data_dir": "/home/user/.monkey_island", + "log_level": "INFO", + "mongodb": { + "start_mongodb": true + }, + "ssl_certificate": { + "ssl_certificate_file": "/home/user/infection_monkey_installation/monkey_island/cc/server.crt", + "ssl_certificate_key_file": "/home/user/infection_monkey_installation/monkey_island/cc/server.crt", + }, + "island_port": 443 +} +``` diff --git a/monkey/monkey_island/cc/setup/island_config_options.py b/monkey/monkey_island/cc/setup/island_config_options.py index 18f503e21bd..45117f7fbee 100644 --- a/monkey/monkey_island/cc/setup/island_config_options.py +++ b/monkey/monkey_island/cc/setup/island_config_options.py @@ -19,22 +19,52 @@ class MongoDBConfig(InfectionMonkeyBaseModel): - start_mongodb: bool = DEFAULT_START_MONGO_DB + start_mongodb: bool = Field( + default=DEFAULT_START_MONGO_DB, + description="If enabled, the MongoDB server will be started automatically with the Island.", + ) # TODO: rename redundant ssl_certificate_file and split the classes into idividual files class SSLCertificatesConfig(InfectionMonkeyBaseModel): ssl_certificate_file: Annotated[ - Path, Field(default=Path(DEFAULT_CRT_PATH)), BeforeValidator(expand_path) + Path, + Field( + default=Path(DEFAULT_CRT_PATH), + description="The path to the SSL certificate file that the Island server will use.", + ), + BeforeValidator(expand_path), ] ssl_certificate_key_file: Annotated[ - Path, Field(default=Path(DEFAULT_KEY_PATH)), BeforeValidator(expand_path) + Path, + Field( + default=Path(DEFAULT_KEY_PATH), + description="The path to the SSL certificate key file that the Island server will use.", + ), + BeforeValidator(expand_path), ] class IslandConfigOptions(InfectionMonkeyBaseModel): - data_dir: Annotated[Path, Field(default=DEFAULT_DATA_DIR), BeforeValidator(expand_path)] - log_level: str = DEFAULT_LOG_LEVEL - mongodb: MongoDBConfig = MongoDBConfig() - ssl_certificate: SSLCertificatesConfig = SSLCertificatesConfig() - island_port: int = DEFAULT_ISLAND_PORT + data_dir: Annotated[ + Path, + Field( + default=DEFAULT_DATA_DIR, + description="The directory where the Island will store runtime artifacts.", + ), + BeforeValidator(expand_path), + ] + log_level: str = Field( + default=DEFAULT_LOG_LEVEL, description="The log level for the Island's logger." + ) + mongodb: MongoDBConfig = Field( + default=MongoDBConfig(), description="The MongoDB configuration for the Island server." + ) + ssl_certificate: SSLCertificatesConfig = Field( + default=SSLCertificatesConfig(), + description="The SSL certificates configuration for the Island server.", + ) + island_port: int = Field( + default=DEFAULT_ISLAND_PORT, + description="The port on which the Island server should listen.", + )