diff --git a/docs/content/FAQ/_index.md b/docs/content/FAQ/_index.md index 922a5e803..0ccbe2872 100644 --- a/docs/content/FAQ/_index.md +++ b/docs/content/FAQ/_index.md @@ -201,25 +201,7 @@ The logs contain information about the internals of the Infection Monkey agent's 2019-07-22 19:16:45,013 [77598:140654230214464:DEBUG] connectionpool._make_request.396: https://updates.infectionmonkey.com:443 "GET / HTTP/1.1" 200 61 ``` -### How do I change the log level of the Monkey Island logger? - -The log level of the Monkey Island logger is set in the `log_level` field -in the `server_config.json` file (located in the [data directory]({{< ref "/reference/data_directory" >}})). -Make sure to leave everything else in `server_config.json` unchanged: - -```json -{ - ... - "log_level": "DEBUG", - ... -} -``` - -Logging levels correspond to [the logging level constants in python](https://docs.python.org/3.7/library/logging.html#logging-levels). - -To apply the changes, reset the Monkey Island process. -On Linux, use `sudo systemctl restart monkey-island.service`. -On Windows, restart the program. +Logging level/verbosity can also be changed, see [setup page](../../setup) for you operating system. ## Running the Infection Monkey in a production environment diff --git a/docs/content/reference/server_configuration.md b/docs/content/reference/server_configuration.md index 60f0dd12c..9e470a19b 100644 --- a/docs/content/reference/server_configuration.md +++ b/docs/content/reference/server_configuration.md @@ -37,64 +37,11 @@ Only relevant options can be specified, for example: } ``` -### Applying configuration to the island +### Configuration options -#### AppImage (Linux) +See setup instructions for your operating system to understand how to apply these. -Specify the path to the `server_config.json` through a command line argument. - -Example: `./InfectionMonkey-v1.12.0.AppImage --server-config="/tmp/server_config.json"` - -#### Windows - -Move the created `server_config.json` to the install directory, monkey island directory. -If you haven't changed the default install directory, the path should look like: - -`C:\Program Files\Guardicore\Monkey Island\monkey\monkey_island\server_config.json` - -#### Docker - -Best way to configure the docker is to is to map server's [data directory](../data_directory) to a volume: - -1. Create a directory for server configuration and other files, e.g. `monkey_island_data`. If you already have it, - **make sure it's empty**. - - ```bash - mkdir ./monkey_island_data - chmod 700 ./monkey_island_data - ``` -1. Establish and populate the created directory with server files (modify the `VERSION` to the one you downloaded): -```bash -sudo docker run \ - --rm \ - --name monkey-island \ - --network=host \ - --user "$(id -u ${USER}):$(id -g ${USER})" \ - --volume "$(realpath ./monkey_island_data)":/monkey_island_data \ - guardicore/monkey-island:VERSION --setup-only -``` - -Once the volume is mapped, we can put `server_config.json` there. -`server_config.json` for docker **must** contain a valid data directory field and `start_mongodb` set to false. - -So, at minimum your `server_config.json` should look like this: - -```json -{ - "data_dir": "/monkey_island_data", - "mongodb": { - "start_mongodb": false - } -} -``` - -Then, the container can be launched by providing `server_config.json` path in the arguments: -```bash -sudo docker run \ - --rm \ - --name monkey-island \ - --network=host \ - --user "$(id -u ${USER}):$(id -g ${USER})" \ - --volume "$(realpath ./monkey_island_data)":/monkey_island_data \ - guardicore/monkey-island:VERSION --server-config="/monkey_island_data/server_config.json" -``` + - `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. diff --git a/docs/content/setup/docker.md b/docs/content/setup/docker.md index 1feeec07d..7c5645bb9 100644 --- a/docs/content/setup/docker.md +++ b/docs/content/setup/docker.md @@ -49,12 +49,12 @@ any MongoDB containers or volumes associated with the previous version. mongo:4.2 ``` -### 3a. Start Monkey Island with default certificate +### 3. Start Monkey Island with default certificate By default, Infection Monkey comes with a [self-signed SSL certificate](https://aboutssl.org/what-is-self-sign-certificate/). In enterprise or other security-sensitive environments, it is recommended that the user [provide Infection Monkey with a -certificate](#3b-start-monkey-island-with-user-provided-certificate) that has +certificate](#start-monkey-island-with-user-provided-certificate) that has been signed by a private certificate authority. 1. Run the Monkey Island server @@ -67,55 +67,90 @@ been signed by a private certificate authority. guardicore/monkey-island:VERSION ``` -### 3b. Start Monkey Island with user-provided certificate -{{% notice info %}} -If you are upgrading the Infection Monkey to a new version, be sure to remove -any volumes associated with the previous version. -{{% /notice %}} +### 4. Accessing Monkey Island -1. [Setup a volume with configuration file](../../reference/server_configuration/#docker). +After the Monkey Island docker container starts, you can access Monkey Island by pointing your browser at `https://localhost:5000`. -1. Move your `.crt` and `.key` files to the volume created in the previous step (`./monkey_island_data`). +## Configuring the server -1. Make sure that your `.crt` and `.key` files are readable and writeable only by you. +You can configure the server by mounting a volume and specifying a + [server configuration file](../../reference/server_configuration): +1. Create a directory for server configuration file, e.g. `monkey_island_data`: ```bash - chmod 600 ./monkey_island_data/ - chmod 600 ./monkey_island_data/ + mkdir ./monkey_island_data + chmod 700 ./monkey_island_data ``` +1. Move your `server_config.json` file to `./monkey_island_data` directory. +1. Run the container with a mounted volume, specify the path to the `server_config.json`: +```bash +sudo docker run \ + --rm \ + --name monkey-island \ + --network=host \ + --user "$(id -u ${USER}):$(id -g ${USER})" \ + --volume "$(realpath ./monkey_island_data)":/monkey_island_data \ + guardicore/monkey-island:VERSION --setup-only --server-config="/monkey_island_data/server_config.json" +``` -1. Edit `./monkey_island_data/server_config.json` to configure Monkey Island - to use your certificate. Your config should look something like this: +### Start Monkey Island with user-provided certificate - ```json {linenos=inline,hl_lines=["11-14"]} +By default, Infection Monkey comes with a [self-signed SSL +certificate](https://aboutssl.org/what-is-self-sign-certificate/). In +enterprise or other security-sensitive environments, it is recommended that the +user provide Infection Monkey with a certificate that has been signed by a +private certificate authority. + +1. Terminate the docker container it's already running. +1. Move your `.crt` and `.key` files to `./monkey_island_data` (directory created for the volume). +1. Make sure that your `.crt` and `.key` files are readable only by you. + ```bash + chmod 600 + chmod 600 + ``` +1. Modify the [server configuration file](../../reference/server_configuration) and add the following lines: + ```json { - "data_dir": "/monkey_island_data", - "mongodb": { - "start_mongodb": false - }, - "ssl_certificate": { - "ssl_certificate_file": "/monkey_island_data/", - "ssl_certificate_key_file": "/monkey_island_data/" - } + "ssl_certificate": { + "ssl_certificate_file": "/monkey_island_data/my_cert.crt", + "ssl_certificate_key_file": "/monkey_island_data/my_key.key" + } } ``` - -1. Start/restart the Monkey Island server: - +1. Run the container with a mounted volume, specify the path to the `server_config.json`: ```bash sudo docker run \ - --tty \ - --interactive \ + --rm \ --name monkey-island \ --network=host \ --user "$(id -u ${USER}):$(id -g ${USER})" \ --volume "$(realpath ./monkey_island_data)":/monkey_island_data \ - guardicore/monkey-island:VERSION --server-config="/monkey_island_data/server_config.json" + guardicore/monkey-island:VERSION --setup-only --server-config="/monkey_island_data/server_config.json" ``` +1. Access the Monkey Island web UI by pointing your browser at + `https://localhost:5000`. -### 4. Accessing Monkey Island +### Change logging level -After the Monkey Island docker container starts, you can access Monkey Island by pointing your browser at `https://localhost:5000`. +1. Stop the docker container it's already running. +1. Modify the [server configuration file](../../reference/server_configuration) by adding the following lines: + ```json + { + "log_level": "INFO" + } + ``` +1. Run the container with a mounted volume, specify the path to the `server_config.json`: + ```bash + sudo docker run \ + --rm \ + --name monkey-island \ + --network=host \ + --user "$(id -u ${USER}):$(id -g ${USER})" \ + --volume "$(realpath ./monkey_island_data)":/monkey_island_data \ + guardicore/monkey-island:VERSION --setup-only --server-config="/monkey_island_data/server_config.json" + ``` +1. Access the Monkey Island web UI by pointing your browser at + `https://localhost:5000`. ## Upgrading diff --git a/docs/content/setup/linux.md b/docs/content/setup/linux.md index b1791c617..2bf318a6b 100644 --- a/docs/content/setup/linux.md +++ b/docs/content/setup/linux.md @@ -46,6 +46,14 @@ do, see the [FAQ]({{< ref >}}) for more information. {{% /notice %}} +## Configuring the server + +You can configure the server by creating +a [server configuration file](../../reference/server_configuration) and +providing a path to it via command line parameters: + +`./InfectionMonkey-v1.12.0.AppImage --server-config="/path/to/server_config.json"` + ### Start Monkey Island with user-provided certificate By default, Infection Monkey comes with a [self-signed SSL @@ -54,13 +62,7 @@ enterprise or other security-sensitive environments, it is recommended that the user provide Infection Monkey with a certificate that has been signed by a private certificate authority. -1. Run the Infection Monkey AppImage package with the `--setup-only` flag to - populate the `$HOME/.monkey_island` directory with a default - `server_config.json` file. - - ```bash - ./InfectionMonkey-v1.12.0.AppImage --setup-only - ``` +1. Terminate the Island process if it's already running. 1. (Optional but recommended) Move your `.crt` and `.key` files to `$HOME/.monkey_island`. @@ -73,6 +75,37 @@ private certificate authority. ``` 1. Create a [server configuration file and provide the path to the certificate](../../reference/server_configuration). +Server configuration file should look something like: + +```json +{ + "ssl_certificate": { + "ssl_certificate_file": "$HOME/.monkey_island/my_cert.crt", + "ssl_certificate_key_file": "$HOME/.monkey_island/my_key.key" + } +} +``` + +1. Start Monkey Island by running the Infection Monkey AppImage package: + ```bash + ./InfectionMonkey-v1.12.0.AppImage --server-config="/path/to/server_config.json" + ``` + +1. Access the Monkey Island web UI by pointing your browser at + `https://localhost:5000`. + +### Change logging level + +1. Terminate the Island process if it's already running. + +1. Create a [server configuration file](../../reference/server_configuration). +Server configuration file should look something like: + +```json +{ + "log_level": "INFO" +} +``` 1. Start Monkey Island by running the Infection Monkey AppImage package: ```bash diff --git a/docs/content/setup/windows.md b/docs/content/setup/windows.md index f76e80de1..cf9dd7e2b 100644 --- a/docs/content/setup/windows.md +++ b/docs/content/setup/windows.md @@ -26,6 +26,11 @@ do, see the [FAQ]({{< ref "/faq/#i-updated-to-a-new-version-of-the-infection-monkey-and-im-being-asked-to-delete-my-existing-data-directory-why" >}}) for more information. {{% /notice %}} +> +## Configuring the server + +You can configure the server by editing [the configuration file](../../reference/server_configuration) located +in installation directory. By default, the path should be `C:\Program Files\Guardicore\Monkey Island\monkey\monkey_island\cc\server_config.json`. ### Start Monkey Island with user-provided certificate @@ -34,14 +39,35 @@ enterprise or other security-sensitive environments, it is recommended that the user provide Infection Monkey with a certificate that has been signed by a private certificate authority. -1. If you haven't already, run the Monkey Island by clicking on the desktop - shortcut. This will populate MongoDB, as well as create and populate - `%AppData%\monkey_island`. 1. Stop the Monkey Island process. 1. (Optional but recommended) Move your `.crt` and `.key` files to `%AppData%\monkey_island`. -1. Create a [server configuration file and provide the path to the certificate](../../reference/server_configuration). +1. Modify the `server_config.json` (by default located in `C:\Program Files\Guardicore\Monkey Island\monkey\monkey_island\cc\server_config.json`) by adding the following lines: + ```json + { + ... + "ssl_certificate": { + "ssl_certificate_file": "%AppData%\\monkey_island\\my_cert.crt", + "ssl_certificate_key_file": "%AppData%\\monkey_island\\my_key.key" + }, + ... + } + ``` 1. Run the Monkey Island by clicking on the desktop shortcut. +1. Access the Monkey Island web UI by pointing your browser at + `https://localhost:5000`. +### Change logging level + +1. Stop the Island server. +1. Modify the `server_config.json` (by default located in `C:\Program Files\Guardicore\Monkey Island\monkey\monkey_island\cc\server_config.json`) by adding the following lines: + ```json + { + ... + "log_level": "INFO", + ... + } + ``` +1. Run the Monkey Island by clicking on the desktop shortcut. 1. Access the Monkey Island web UI by pointing your browser at `https://localhost:5000`.