diff --git a/docs/configuration.md b/docs/configuration.md index 582284b..e802253 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -51,12 +51,6 @@ ssl_port: 7130 # The port to listen on for SSL (HTTPS) connections. Note that the HTTPS # server will only be started of the certificate and key options outlined # below are provided. The default is 7130. -ssl_certificate_path: -# The path to a self signed ssl certificate. The default is no path, which -# disables HTTPS. -ssl_key_path: -# The path to the private key used to signed the certificate. The default -# is no path, which disables HTTPS. klippy_uds_address: /tmp/klippy_uds # The address of Unix Domain Socket used to communicate with Klippy. Default # is /tmp/klippy_uds @@ -67,6 +61,15 @@ enable_debug_logging: False # of development the default is False. ``` +!!! Note: + Previously the `[server]` section contained `ssl_certificate_path` and + `ssl_key_path` options. These options are now deprecated, as both locations + are determined by the `data path` and `alias` configured on the command + line, ie `/certs/.cert`. By default the certificate + path resolves to `$HOME/moonraker_data/certs/moonraker.cert` and the key + path resolves to `$HOME/moonraker_data/certs/moonraker.key`. Both files + may be symbolic links. + ### `[file_manager]` The `file_manager` section provides configuration for Moonraker's file @@ -74,18 +77,6 @@ management functionality. If omitted defaults will be used. ```ini # moonraker.conf - -config_path: -# The path to a directory where configuration files are located. This -# directory may contain Klipper config files (printer.cfg) or Moonraker -# config files (moonraker.conf). Clients may also write their own config -# files to this directory. Note that this may not be the system root -# (ie: "/") and moonraker must have read and write access permissions -# for this directory. -log_path: -# An optional path to a directory where log files are located. Users may -# configure various applications to store logs here and Moonraker will serve -# them at "/server/files/logs/*". The default is no log paths. queue_gcode_uploads: False # When set to True the file manager will add uploads to the job_queue when # the `start_print` flag has been set. The default if False. @@ -96,17 +87,17 @@ enable_object_processing: False # "cancel object" functionality. Note that this process is file I/O intensive, # it is not recommended for usage on low resource SBCs such as a Pi Zero. # The default is False. +enable_inotify_warnings: True +# When set to True Moonraker will generate warnings when inotify attempts +# to add a duplicate watch or when inotify encounters an error. On some +# file systems inotify may not work as expected, this gives users the +# option to suppress warnings when necessary. The default is True. ``` -!!! Warning - Moonraker currently supports two paths with read/write access, the - `config_path` configured in the `file_manager` and the `virtual_sdcard` path - configured through Klipper in `printer.cfg`. These paths are monitored for - changes, thus they must not overlap. Likewise, these paths may not be a - parent or child of folders containing sensitive files such as the `database`, - Moonraker's source, or Klipper's source. If either of the above conditions - are present Moonraker will generate a warning and revoke access to the - offending path. +!!! Note: + Previously the `[file_manager]` section contained `config_path` and + `log_path` options. These options are now deprecated, as both locations + are determined by the `data path` configured on the command line. !!! Tip It is also possible to enable object processing directly in the slicer. @@ -169,24 +160,11 @@ gcode: ### `[database]` -The `database` section provides configuration for Moonraker's lmdb database. -If omitted defaults will be used. - -```ini -moonraker.conf - -database_path: ~/.moonraker_database -# The path to the folder that stores Moonraker's lmdb database files. -# It is NOT recommended to place this file in a location that is served by -# Moonraker (such as the "config_path" or the location where gcode -# files are stored). If the folder does not exist an attempt will be made -# to create it. The default is ~/.moonraker_database. -``` - -!!! Note - Previously the `enable_database_debug` option was available for internal - development to test changes to write protected namespaces. This option - been deprecated and disabled. +!!! Note: + This section no long has configuration options. Previously the + `database_path` option was used to determine the locatation of + the database folder, it is now determined by the `data path` + configured on the command line. ### `[data_store]` @@ -1804,23 +1782,15 @@ separate from `moonraker.conf`. This allows users to safely distribute their configuration and log files without revealing credentials and other sensitive information. -```ini -# moonraker.conf +!!! Note: + This section no long has configuration options. Previously the + `secrets_path` option was used to specify the location of the file. + The secrets file name and location is now determined by the `data path` + and `alias` command line options, ie: `/.secrets`. + By default this resolves to `$HOME/moonraker_data/moonraker.secrets`. + This may be a symbolic link. -[secrets] -secrets_path: -# A valid path to the "secrets" file. A secrets file should either be -# in "ini" format (ie: the same format as moonraker.conf) or "json" -# format. If the file is a "json" file, the top level item must be -# an Object. When this parameter is not specified no file will be -# loaded. -``` - -!!! Warning - For maximum security the secrets file should be located in a folder - not served by Moonraker. - -Example ini file: +Example ini secrets file: ```ini # moonraker_secrets.ini @@ -1834,7 +1804,7 @@ token: long_token_string ``` -Example json file: +Example json secrets file: ```json { diff --git a/docs/installation.md b/docs/installation.md index 396b574..00a47f6 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -31,7 +31,7 @@ missing one or both, you can simply add the bare sections to `printer.cfg`: [display_status] [virtual_sdcard] -path: ~/gcode_files +path: ~/moonraker_data/gcodes ``` ### Enabling the Unix Socket @@ -69,12 +69,9 @@ KLIPPY_ARGS="/home/pi/klipper/klippy/klippy.py /home/pi/printer.cfg -l /tmp/klip the default LSB script. In this case, you need to modify the klipper.service file. -You may also want to take this opportunity to change the location of -printer.cfg to match Moonraker's `config_path` option (see the -[configuration document](configuration.md#primary-configuration) -for more information on the config_path). For example, if the `config_path` -is set to `~/printer_config`, your klipper defaults file might look -like the following: +You may also want to take this opportunity to configure `printer.cfg` and +`klippy.log` so they are located in Moonraker's `data_path`, for example: + ``` # Configuration for /etc/init.d/klipper @@ -82,14 +79,17 @@ KLIPPY_USER=pi KLIPPY_EXEC=/home/pi/klippy-env/bin/python -KLIPPY_ARGS="/home/pi/klipper/klippy/klippy.py /home/pi/printer_config/printer.cfg -l /tmp/klippy.log -a /tmp/klippy_uds" +KLIPPY_ARGS="/home/pi/klipper/klippy/klippy.py /home/pi/moonraker_data/config/printer.cfg -l /home/pi/moonraker_data/logs/klippy.log -a /tmp/klippy_uds" ``` -If necessary, create the config directory and move printer.cfg to it: +Moonraker's install script will create the data folder, however you +may wish to create it now and move `printer.cfg` to the correct +location, ie: ``` -cd ~ -mkdir printer_config -mv printer.cfg printer_config +mkdir ~/moonraker_data +mkdir ~/moonraker_data/logs +mkdir ~/moonraker_data/config +mv printer.cfg ~/moonraker_data/config ``` ### Installing Moonraker @@ -101,10 +101,15 @@ cd ~ git clone https://github.com/Arksine/moonraker.git ``` -Now is a good time to create [moonraker.conf](configuration.md). If you are -using the `config_path`, create it in the specified directory otherwise create -it in the HOME directory. The [sample moonraker.conf](./moonraker.conf) in -the `docs` directory may be used as a starting point. +The install script will attempt to create a basic configuration if +`moonraker.conf` does not exist at the expected location, however if you +prefer to have Moonraker start with a robust configuration you may create +it now. By default the configuration file should be located at +`$HOME/moonraker_data/config/moonraker.conf`, however the location of the +data path may be configured using the script's command line options. +The [sample moonraker.conf](./moonraker.conf) may be used as a starting +point, full details can be found in the +[confguration documentation](./configuration.md). For a default installation run the following commands: ``` @@ -112,29 +117,38 @@ cd ~/moonraker/scripts ./install-moonraker.sh ``` -Or to install with `moonraker.conf` in the `config_path`: -``` -cd ~/moonraker/scripts -./install-moonraker.sh -f -c /home/pi/printer_config/moonraker.conf -``` - The install script has a few command line options that may be useful, particularly for those upgrading: -- `-r`: - Rebuilds the virtual environment for existing installations. - Sometimes this is necessary when a dependency has been added. - `-f`: Force an overwrite of Moonraker's systemd script. By default the the systemd script will not be modified if it exists. -- `-c /home/pi/moonraker.conf`: - Specifies the path to Moonraker's config file. The default location - is `/home//moonraker.conf`. When using this option to modify - an existing installation it is necessary to add `-f` as well. +- `-a `: + The alias used for this instance of Moonraker. Moonraker uses this option + when determining the file names for the configuration file, log file, + secrets file, etc. This option is also used to name Moonraker's systemd + service unit and enviroment file. If omitted this defaults to `moonraker`. +- `-d `: + Specifies the path to Moonraker's data folder. This folder organizes + files and directories used by moonraker. See the `Data Folder Structure` + section for details. If omitted this defaults to `$HOME/_data`, + ie: `/home/pi/moonraker_data`. +- `-c ` + Specifies the path to Moonraker's configuation file. By default the + configuration is expected at `/config/.conf`. ie: + `/home/pi/moonraker_data/config/moonraker.conf`. +- `-l ` + Specifies the path to Moonraker's log file. By default Moonraker logs + to `/logs/.log`. ie: + `/home/pi/moonraker_data/logs/moonraker.log`. - `-z`: Disables `systemctl` commands during install (ie: daemon-reload, restart). This is useful for installations that occur outside of a standard environment where systemd is not running. +- `-x`: + Skips installation of [polkit rules](#policykit-permissions). This may be + necessary to install Moonraker on systems that do not have policykit + installed. Additionally, installation may be customized with the following environment variables: @@ -143,11 +157,13 @@ variables: - `MOONRAKER_REBUILD_ENV` - `MOONRAKER_FORCE_DEFAULTS` - `MOONRAKER_DISABLE_SYSTEMCTL` +- `MOONRAKER_SKIP_POLKIT` - `MOONRAKER_CONFIG_PATH` -- `MOONRAKER_LOG_PATH` +- `MOONAKER_LOG_PATH` +- `MOONRAKER_DATA_PATH` When the script completes it should start both Moonraker and Klipper. In -`/tmp/klippy.log` you should find the following entry: +`klippy.log` you should find the following entry: `webhooks client : Client info {'program': 'Moonraker', 'version': ''}` @@ -162,18 +178,197 @@ Now you may install a client, such as debian/ubuntu distros). +### Data Folder Structure + +As mentioned previously, files and folders used by Moonraker are organized +in a primary data folder. The example below illustrates the folder +structure using the default data path of `$HOME/moonraker_data` and the +default alias of `moonraker`: + +``` +/home/pi/moonraker_data +├── backup +│   └── 20220822T202419Z +│   ├── config +│   │   └── moonraker.conf +│   └── service +│   └── moonraker.service +├── certs +│   ├── moonraker.cert (optional) +│   └── moonraker.key (optional) +├── config +│   ├── moonraker.conf +│   └── printer.cfg +├── database +│   ├── data.mdb +│   └── lock.mdb +├── gcodes +│   ├── test_gcode_one.gcode +│   └── test_gcode_two.gcode +├── logs +│   ├── klippy.log +│   └── moonraker.log +└── moonraker.secrets (optional) +``` + +The next example illustrates how the `` and `` +command line options are used to populate the folder: + +``` + +├── backup +│   └── +│   ├── config +│   │   └── +│   └── service +│   └── +├── certs +│   ├── .cert (optional) +│   └── .key (optional) +├── config +│   ├── .conf +│   └── printer.cfg +├── database +│   ├── data.mdb +│   └── lock.mdb +├── gcodes +│   ├── test_gcode_one.gcode +│   └── test_gcode_two.gcode +├── logs +│   ├── klippy.log +│   └── .log +└── .secrets (optional) +``` + +If it is not desirible for the files and folders to exist in these specific +locations it is acceptable to use symbolic links. For example, it is common +for the gcode folder to be located at `$HOME/gcode_files`. Rather than +reconfigure Klipper's `virtual_sdcard` it may be desirable to create a +`gcodes` symbolic link in the data path pointing to this location. + +!!! Note + It is still possible to directly configure the paths to the configuration + and log files if you do not wish to use the default `` naming + scheme or if you wish for them to exist outside of the data folder. + +When Moonraker attempts to update legacy installations symbolic links +are used to avoid an unrecoverable error. Additionally a `backup` +folder is created which contains the prior configuration and/or +systemd service unit, ie: + +``` +/home/pi/moonraker_data +├── backup +│   └── 20220822T202419Z +│   ├── config +│   │   ├── include +│   │   │   ├── extras.conf +│   │   │   ├── power.conf +│   │   │   └── updates.conf +│   │   └── moonraker.conf +│   └── service +│   └── moonraker.service +├── certs +│   ├── moonraker.cert -> /home/pi/certs/certificate.pem +│   └── moonraker.key -> /home/pi/certs/key.pem +├── config -> /home/pi/klipper_config +├── database -> /home/pi/.moonraker_database +├── gcodes -> /home/pi/gcode_files +├── logs -> /home/pi/logs +└── moonraker.secrets -> /home/pi/moonraker_secrets.ini +``` + +!!! Warning + The gcode and config paths should not contain symbolic links + that result in an "overlap" of on another. Moonraker uses + inotify to watch files in each of these folders and takes action + when a file change is detected. The action taken depends on the + "root" folder, thus it is important that they be distinct. + +### The systemd service file + +The default installation will create `/etc/systemd/system/moonraker.service`. +Below is a common example of service file, installed on a Raspberry Pi: + +```ini +# systemd service file for moonraker +[Unit] +Description=API Server for Klipper SV1 +Requires=network-online.target +After=network-online.target + +[Install] +WantedBy=multi-user.target + +[Service] +Type=simple +User=pi +SupplementaryGroups=moonraker-admin +RemainAfterExit=yes +WorkingDirectory=/home/pi/moonraker +EnvironmentFile=/home/pi/moonraker/moonraker.env +ExecStart=/home/pi/moonraker-env/bin/python $MOONRAKER_ARGS +Restart=always +RestartSec=10 +``` + +Following are some items to take note of: + +- The `Description` contains a string that Moonraker uses to validate + the version of the service file, (notice `SV1` at the end, ie: Service + Version 1). +- The `moonraker-admin` supplementary group is used to grant policykit + permissions. +- The `EnvironmentFile` field contains Moonraker's arguments. More on this + below. +- The `ExecStart` field begins with the python executable, followed by + by the enviroment variable `MOONRAKER_ARGS`. This variable is set in + the environment file. + +#### The Enivirorment File + +The environment file is created in Moonraker's source directory during +installation. By default the enviroment file is named `moonraker.env`. +A default installation's enviroment file will contain the path +to `moonraker.py` and the alias option, ie: + +``` +MOONRAKER_ARGS="/home/pi/moonraker/moonraker/moonraker.py -a moonraker" +``` + +A legacy installation converted to the updated flexible service unit +might contain the following: + +``` +MOONRAKER_ARGS="/home/pi/moonraker/moonraker/moonraker.py -a moonraker -d /home/pi/moonraker_data -c /home/pi/klipper_config/moonraker.conf -l /home/pi/klipper_logs/moonraker.log" +``` + +Post installation it is simple to customize the [arguments](#command-line-usage) +supplied to Moonraker by editing this file and restarting the service. + +!!! Note + The service unit and enviroment file are named based on the `alias` + option supplied to the install script, which is `moonraker` by default. + Supplying `-a moonraker_1` to the install script will result in a + service file named `moonraker_1.service` and an environment file + named `moonraker_1.env`. + ### Command line usage This section is intended for users that need to write their own installation script. Detailed are the command line arguments available to Moonraker: ``` -usage: moonraker.py [-h] [-c ] [-l ] [-n] +usage: moonraker.py [-h] [-a ] [-d ] [-c ] [-l ] [-n] Moonraker - Klipper API Server -optional arguments: +options: -h, --help show this help message and exit + -a , --alias + Alternate name of instance + -d , --datapath + Location of Moonraker Data File Path -c , --configfile Location of moonraker configuration file -l , --logfile @@ -182,22 +377,28 @@ optional arguments: ``` The default configuration is: -- config file path- `~/moonraker.conf` -- log file path - `/tmp/moonraker.log` +- `data path`: `$HOME/moonraker_data` +- `alias`: `moonraker` +- `config file`: `$HOME/moonraker_data/config/moonraker.conf` +- `log file`: `$HOME/moonraker_data/logs/moonraker.log` - logging to a file is enabled -If one needs to start moonraker without generating a log file, the +!!! Tip + While the `alias` option may be omitted it is recommended that it + always be included for new installations. This allows Moonraker + to differentiate between new and legacy installations. + +If is necessary to run Moonraker without logging to a file the `-n` option may be used, for example: ``` -~/moonraker-env/bin/python ~/moonraker/moonraker/moonraker.py -n -c /path/to/moonraker.conf +~/moonraker-env/bin/python ~/moonraker/moonraker/moonraker.py -n ``` -In general it is not recommended to install moonraker with this option. -While moonraker will still log to stdout, all requests for support must -be accompanied by moonraker.log. -These options may be changed by editing -`/etc/systemd/system/moonraker.service`. The `install-moonraker.sh` script -may also be used to modify the config file location. +In general it is not recommended to install Moonraker with file logging +disabled. While moonraker will still log to stdout, all requests for support +must be accompanied by moonraker.log. + +These options may be changed by editing `moonraker.env`. ### PolicyKit Permissions @@ -326,17 +527,3 @@ rm -rf klipper git clone https://github.com/Klipper3d/klipper.git sudo systemctl restart klipper ``` - -### Additional Notes - -- Make sure that Moonraker and Klipper both have read and write access to the - directory set in the `path` option for the `[virtual_sdcard]` in - `printer.cfg`. -- Upon first starting Moonraker is not aware of the gcode file path, thus - it cannot serve gcode files, add directories, etc. After Klippy enters - the "ready" state it sends Moonraker the gcode file path. - Once Moonraker receives the path it will retain it regardless of Klippy's - state, and update it if the path is changed in printer.cfg. - -Please see [configuration.md](configuration.md) for details on how to -configure moonraker.conf. diff --git a/docs/moonraker.conf b/docs/moonraker.conf index c2d7822..9951da2 100644 --- a/docs/moonraker.conf +++ b/docs/moonraker.conf @@ -6,8 +6,7 @@ [server] # Bind server defaults of 0.0.0.0, port 7125 -enable_debug_logging: True -config_path: ~/printer_config +enable_debug_logging: False [authorization] enabled: True