3diy
/
moonraker
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: update deprecations 

Signed-off-by:  Eric Callahan <arksine.code@gmail.com>
This commit is contained in:
Eric Callahan 2022-10-10 12:08:04 -04:00 committed by Eric Callahan
parent 485b29490a
commit 2603cc2e8f
4 changed files with 238 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
docs/configuration.md
View File

@ -57,8 +57,8 @@ klippy_uds_address: /tmp/klippy_uds
max_upload_size: 1024
# The maximum size allowed for a file upload (in MiB). Default is 1024 MiB.
enable_debug_logging: False
# When set to True Moonraker will log in verbose mode. During this stage
# of development the default is False.
# ***DEPRECATED***
# Verbose logging is enabled by the '-v' command line option.
```
!!! Note:
@ -1201,11 +1201,8 @@ disk or cloned from unofficial sources are not supported.
[update_manager]
enable_repo_debug: False
# When set to True moonraker will bypass repo validation and allow
# updates from unofficial remotes and/or branches. Updates on
# detached repos are also allowed. This option is intended for
# developers and should not be used on production machines. The
# default is False.
# ***DEPRECATED***
# Debug features are now enabled by the '-g' command line option
enable_auto_refresh: False
# When set to True Moonraker will attempt to fetch status about
# available updates roughly every 24 hours, between 12am-4am.
@ -2105,12 +2102,10 @@ for core component configuration if no section was present.
On April 6th 2022 the fallback was deprecated. Moonraker will still function
normally if `core components` are configured in the `[server]` section,
however Moonraker now generates warnings when it detected this condition,
however Moonraker now generates warnings when it detects this condition,
such as:
```
[server]: Option 'config_path' has been moved to section [file_manager]. Please correct your configuration, see https://moonraker.readthedocs.io/en/latest/configuration for detailed documentation.
[server]: Option 'log_path' has been moved to section [file_manager]. Please correct your configuration, see https://moonraker.readthedocs.io/en/latest/configuration for detailed documentation.
[server]: Option 'temperature_store_size' has been moved to section [data_store]. Please correct your configuration, see https://moonraker.readthedocs.io/en/latest/configuration for detailed documentation.
[server]: Option 'gcode_store_size' has been moved to section [data_store]. Please correct your configuration, see https://moonraker.readthedocs.io/en/latest/configuration for detailed documentation
```
@ -2126,8 +2121,6 @@ host: 0.0.0.0
port: 7125
temperature_store_size: 600
gcode_store_size: 1000
config_path: ~/klipper_config
log_path: ~/klipper_logs
```
@ -2140,10 +2133,6 @@ You will need to change it to the following;
host: 0.0.0.0
port: 7125
[file_manager]
config_path: ~/klipper_config
log_path: ~/klipper_logs
[data_store]
temperature_store_size: 600
gcode_store_size: 1000
@ -2159,8 +2148,3 @@ make the changes.
Once the changes are complete you may use the UI to restart Moonraker and
the warnings should clear.
!!! Note
Some users have asked why Moonraker does not automate these changes.
Currently Moonraker has no mechanism to modify the configuration directly,
however this functionality will be added in the future.

83
docs/installation.md
View File

@ -298,7 +298,7 @@ Following are some items to take note of:
by the enviroment variable `MOONRAKER_ARGS`. This variable is set in
the environment file.
#### The Enivirorment File
#### The Enivironment File
The environment file, `moonraker.env`. is created in the data path during
installation. A default installation's enviroment file will contain the path
@ -338,6 +338,9 @@ options:
-l <logfile>, --logfile <logfile>
log file name and location
-n, --nologfile disable logging to a file
-v, --verbose Enable verbose logging
-g, --debug Enable Moonraker debug features
-o, --asyncio-debug Enable asyncio debug flag
```
The default configuration is:
@ -345,6 +348,9 @@ The default configuration is:
- `config file`: `$HOME/printer_data/config/moonraker.conf`
- `log file`: `$HOME/printer_data/logs/moonraker.log`
- logging to a file is enabled
- Verbose logging is disabled
- Moonraker's debug features are disabled
- The asyncio debug flag is set to false
!!! Tip
While the `data path` option may be omitted it is recommended that it
@ -354,7 +360,7 @@ The default configuration is:
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
~/moonraker-env/bin/python ~/moonraker/moonraker/moonraker.py -d ~/printer_data -n
```
In general it is not recommended to install Moonraker with file logging
@ -431,6 +437,37 @@ enable_system_updates: False
Previously installed PolicyKit rules can be removed by running
`set-policykit-rules.sh -c`
### Completing Privileged Upgrades
At times an update to Moonraker may require a change to the systemd service
file, which requires sudo permission to complete. Moonraker will present
an announcement when it need's the user's password and the process can
be completed by entering the password through Moonraker's landing page.
Some users prefer not to provide these credentials via the web browser and
instead would like to do so over ssh. These users may run
`scripts/finish-upgrade.sh` to provide Moonraker the necessary credentials
via ssh:
```
Utility to complete privileged upgrades for Moonraker
usage: finish-upgrade.sh [-h] [-a <address>] [-p <port>] [-k <api_key>]
optional arguments:
-h show this message
-a <address> address for Moonraker instance
-p <port> port for Moonraker instance
-k <api_key> API Key for authorization
```
By default the script will connect to a Moonraker instances on the local
machine at port 7125. If the instance is not bound to localhost or is
bound to another port the user may specify a custom address and port.
The API Key (`-k`) option is only necessary if the localhost is not authorized
to access Moonraker's API.
### Retrieving the API Key
Some clients may require an API Key to connect to Moonraker. After the
@ -490,3 +527,45 @@ rm -rf klipper
git clone https://github.com/Klipper3d/klipper.git
sudo systemctl restart klipper
```
### Debug options for developers
Moonraker accepts several command line arguments that can be used to
assist both front end developers and developers interested in extending
Moonraker.
- The `-v` (`--verbose`) argument enables verbose logging. This includes
logging that reports information on all requests received and responses.
- The `-g` (`--debug`) argument enables Moonraker's debug features,
including:
- Debug endpoints
- The `update_manager` will bypass strict git repo validation, allowing
updates from unofficial remotes and repos in a `detached HEAD` state.
- The `-o` (`--asyncio-debug`) argument enables the asyncio debug flag. This
will substantially increase logging and is intended for low level debugging
of the asyncio event loop.
!!! Warning
The debug option should not be enabled in production environments. The
database debug endpoints grant read/write access to all namespaces,
including those typically exclusive to Moonraker. Items such as user
credentials are exposed.
Installations using systemd can enable debug options by editing `moonraker.env`
via ssh:
```
nano ~/printer_data/systemd/moonraker.env
```
Once the file is open, append the debug option(s) (`-v` and `-g` in this example) to the
value of `MOONRAKER_ARGS`:
```
MOONRAKER_ARGS="/home/pi/moonraker/moonraker/moonraker.py -d /home/pi/printer_data -c /home/pi/klipper_config/moonraker.conf -l /home/pi/klipper_logs/moonraker.log -v -g"
```
Save the file, exit the text editor, and restart the Moonraker service:
```
sudo systemctl restart moonraker
```

24
docs/user_changes.md
View File

@ -2,6 +2,30 @@
This file will track changes that require user intervention,
such as a configuration change or a reinstallation.
### October 14th 2022
- The systemd service file is now versioned. Moonraker can now detect when
the file is out of date and automate corrections as necessary.
- Moonraker's command line options are now specified in an environment file,
making it possible to change these options without modifying the service file
and reloading the systemd daemon. The default location of the environment
file is `~/printer_data/systemd/moonraker.env`.
- Moonraker now manages files and folders in a primary data folder supplied
by the `-d` (`--data-path`) command line option. As a result, the following
options have been deprecated:
- `ssl_certificate_path` in `[server]`
- `ssl_key_path` in `[server]`
- `database_path` in `[database]`
- `config_path` in `[file_manager]`
- `log_path` in `[file_manager]`
- `secrets_path` in `[secrets]`
- Debugging options are now supplied to Moonraker via the command line.
The `-v` (`--verbose`) option enables verbose logging, while the `-g`
(`--debug`) option enables debug features, including access to debug
endpoints and the repo debug feature in `update_manager`. As a result,
the following options are deprecated:
- `enable_debug_logging` in `[server]`
- `enable_repo_debug` in `[update_manager]`
### July 27th 2022
- The behavior of `[include]` directives has changed. Included files
are now parsed as they are encountered. If sections are duplicated

128
docs/web_api.md
View File

@ -2333,6 +2333,7 @@ HTTP request:
```http
GET /server/database/list
```
JSON-RPC request:
```json
{
@ -4936,6 +4937,133 @@ Returns:
returned. Once received, Moonraker will broadcast this event via
the [agent event notification](#agent-events) to all other connections.
### Debug APIs
The APIs in this section are available when Moonraker the debug argument
(`-g`) has been supplied via the command line. Some API may also depend
on Moonraker's configuration, ie: an optional component may choose to
register a debug API.
!!! Warning
Debug APIs may expose security vulnerabilities. They should only be
enabled by developers on secured machines.
#### List Database Namespaces (debug)
Debug version of [List Namespaces](#list-namespaces). Return value includes
namespaces exlusively reserved for Moonraker. Only availble when Moonraker's
debug features are enabled.
HTTP request:
```http
GET /debug/database/list
```
JSON-RPC request:
```json
{
"jsonrpc": "2.0",
"method": "debug.database.list",
"id": 8694
}
```
#### Get Database Item (debug)
Debug version of [Get Database Item](#get-database-item). Keys within
protected and forbidden namespaces are accessible. Only availble when
Moonraker's debug features are enabled.
!!! Warning
Moonraker's forbidden namespaces include items such as user credentials.
This endpoint should NOT be implemented in front ends directly.
HTTP request:
```http
GET /debug/database/item?namespace={namespace}&key={key}
```
JSON-RPC request:
```json
{
"jsonrpc": "2.0",
"method": "debug.database.get_item",
"params": {
"namespace": "{namespace}",
"key": "{key}"
},
"id": 5644
}
```
#### Add Database Item (debug)
Debug version of [Add Database Item](#add-database-item). Keys within
protected and forbidden namespaces may be added. Only availble when
Moonraker's debug features are enabled.
!!! Warning
This endpoint should be used for testing/debugging purposes only.
Modifying protected namespaces outside of Moonraker can result in
broken functionality and is not supported for production environments.
Issues opened with reports/queries related to this endpoint will be
redirected to this documentation and closed.
```http
POST /debug/database/item
Content-Type: application/json
{
"namespace": "my_client",
"key": "settings.some_count",
"value": 100
}
```
JSON-RPC request:
```json
{
"jsonrpc": "2.0",
"method": "debug.database.post_item",
"params": {
"namespace": "{namespace}",
"key": "{key}",
"value": 100
},
"id": 4654
}
```
#### Delete Database Item (debug)
Debug version of [Delete Database Item](#delete-database-item). Keys within
protected and forbidden namespaces may be removed. Only availble when
Moonraker's debug features are enabled.
!!! Warning
This endpoint should be used for testing/debugging purposes only.
Modifying protected namespaces outside of Moonraker can result in
broken functionality and is not supported for production environments.
Issues opened with reports/queries related to this endpoint will be
redirected to this documentation and closed.
HTTP request:
```http
DELETE /debug/database/item?namespace={namespace}&key={key}
```
JSON-RPC request:
```json
{
"jsonrpc": "2.0",
"method": "debug.database.delete_item",
"params": {
"namespace": "{namespace}",
"key": "{key}"
},
"id": 4654
}
```
### Websocket notifications
Printer generated events are sent over the websocket as JSON-RPC 2.0
notifications. These notifications are sent to all connected clients