diff --git a/pterodactyl/remote/README.md b/pterodactyl/remote/README.md index 0d807d5..0ea9e19 100644 --- a/pterodactyl/remote/README.md +++ b/pterodactyl/remote/README.md @@ -2,6 +2,6 @@ This API is used for Wings communication and is primarily for Wings, but can be accessed externally. This API is not documented so there is very little information about it. -# Access +## Access -Unknown. +The `Authorization` header must be present in the requests and must be prefixed with "Bearer " followed by the node's token_id, a period, then the node's token. The token can be obtained in the configuration page of a node in the admin panel, or from the [node configuration endpoint](/pterodactyl/application/nodes.md#get-nodesidconfiguration) in the application API. The `Accept` header must be set to "application/json" for requests, and the `Content-Type` must be set to "application/json" when making `POST` requests. diff --git a/pterodactyl/remote/activity_events.md b/pterodactyl/remote/activity_events.md new file mode 100644 index 0000000..f787c87 --- /dev/null +++ b/pterodactyl/remote/activity_events.md @@ -0,0 +1,65 @@ +# Activity events + +Here are a list of activity events, which are used in the audit log feature. + +```text +server.backup.restore-failed +server:allocation.create +server:allocation.delete +server:allocation.notes +server:allocation.primary +server:backup.complete +server:backup.delete +server:backup.download +server:backup.fail +server:backup.lock +server:backup.restore +server:backup.restore-complete +server:backup.restore-failed +server:backup.restore-started +server:backup.start +server:backup.unlock +server:console.command +server:console.command +server:database.create +server:database.delete +server:database.rotate-password +server:file.compress +server:file.copy +server:file.create-directory +server:file.decompress +server:file.delete +server:file.download +server:file.pull +server:file.read +server:file.rename +server:file.uploaded +server:file.write +server:power.kill +server:power.restart +server:power.start +server:power.stop +server:reinstall +server:schedule.create +server:schedule.delete +server:schedule.execute +server:schedule.update +server:settings.description +server:settings.rename +server:sftp.create +server:sftp.create-directory +server:sftp.delete +server:sftp.denied +server:sftp.rename +server:sftp.write +server:startup.edit +server:startup.image +server:subuser.create +server:subuser.delete +server:subuser.update +server:task.create +server:task.delete +server:task.update + +* If there are any missing events, feel free to open a pull request. +``` diff --git a/pterodactyl/remote/server_backups.md b/pterodactyl/remote/server_backups.md new file mode 100644 index 0000000..872cab5 --- /dev/null +++ b/pterodactyl/remote/server_backups.md @@ -0,0 +1,90 @@ +### `GET /api/remote/backups/:backup` + +Returns the required presigned urls to upload a backup to S3 cloud storage. + +### Parameters + +| Name | Visibility | Description | +| --------- | ---------- | ---------------------------------- | +| size | required | The backup file size. | + +### Responses + +| Code | Description | +| ---- | -------------------------------------------------------------- | +| 200 | The response was successful. | +| 400 | The configured backup adapter is not an S3 compatible adapter. | +| 404 | The backup was not found. | +| 409 | The backup is already in completed state. | + +Sources + +- [app/Http/Controllers/Api/Remote/Backups/BackupRemoteUpl2oadController.php#L33](https://github.com/pterodactyl/panel/blob/v1.11.3/app/Http/Controllers/Api/Remote/Backups/BackupRemoteUploadController.php#L33) + +### `POST /api/remote/backups/:backup` + +Handles updating the state of a backup. + +### Body + +| Name | Visibility | Type | Description | +| ------------------------ | --------------------------- | ------- | ------------------------------------------------------------------------------------------------------ | +| data | required | object | An object containing the checksum, checksum type, backup size, success state, and parts of the backup. | +| data.successful | required | boolean | The success state of the backup. | +| data.checksum | required if success is true | string | The checksum. | +| data.checksum_type | required if success is true | string | The checksum type. | +| data.size | required if success is true | number | The size of the backup. | +| data.parts | optional | array | An array containing the etag and part number for each part. | +| data.parts[].etag | required | string | ??? | +| data.parts[].part_number | required | number | ??? | + +### Example Body + +```json +{ + "data": { + "checksum": "a0b124c3def45g67890h12i3j4567k8l9mn01234", + "checksum_type": "sha1", + "size": 1234, + "successful": true, + "parts": null + } +} +``` + +Note: `parts` can also be defined as an array with objects with the keys `etag` (string) and `part_number` (number). + +### Responses + +| Code | Description | +| ---- | ----------------------------------------- | +| 204 | The response was successful. | +| 400 | The backup is already in completed state. | +| 404 | The backup was not found. | + +Sources + +- [app/Http/Controllers/Api/Remote/Backups/BackupStatusController.php#L31](https://github.com/pterodactyl/panel/blob/v1.11.3/app/Http/Controllers/Api/Remote/Backups/BackupStatusController.php#L31) + +--- + +### `POST /api/remote/backups/:backup/restore` + +Handles toggling the restoration status of a server. + +### Body + +| Name | Visibility | Type | Description | +| ---------- | ---------- | ------- | -------------------------------------------- | +| successful | required | boolean | The success state of the backup restoration. | + +### Responses + +| Code | Description | +| ---- | ---------------------------- | +| 204 | The response was successful. | +| 404 | The backup was not found. | + +Sources + +- [app/Http/Controllers/Api/Remote/Backups/BackupStatusController.php#L78](https://github.com/pterodactyl/panel/blob/v1.11.3/app/Http/Controllers/Api/Remote/Backups/BackupStatusController.php#L78) diff --git a/pterodactyl/remote/server_installation.md b/pterodactyl/remote/server_installation.md new file mode 100644 index 0000000..8caa914 --- /dev/null +++ b/pterodactyl/remote/server_installation.md @@ -0,0 +1,158 @@ +### `GET /api/remote/servers/:uuid` + +Returns details about the server that allows Wings to self-recover and ensure that the state of the server matches the Panel at all times. + +### Responses + +| Code | Description | +| ---- | --------------------------- | +| 200 | The request was successful. | +| 404 | The server was not found. | + +### Response example + +```json +{ + "settings": { + "uuid": "1abc23d4-567e-8f9g-9h01-2ij34k56lmno", + "meta": { + "name": "My server", + "description": "" + }, + "suspended": false, + "environment": { + "SERVER_JARFILE": "server.jar", + "MC_VERSION": "latest", + "BUILD_TYPE": "recommended", + "FORGE_VERSION": "", + "STARTUP": "java -Xms128M -XX:MaxRAMPercentage=95.0 -Dterminal.jline=false -Dterminal.ansi=true $( [[ ! -f unix_args.txt ]] && printf %s \"-jar {{SERVER_JARFILE}}\" || printf %s \"@unix_args.txt\" )", + "P_SERVER_LOCATION": "home", + "P_SERVER_UUID": "1abc23d4-567e-8f9g-9h01-2ij34k56lmno", + "P_SERVER_ALLOCATION_LIMIT": 0 + }, + "invocation": "java -Xms128M -XX:MaxRAMPercentage=95.0 -Dterminal.jline=false -Dterminal.ansi=true $( [[ ! -f unix_args.txt ]] && printf %s \"-jar {{SERVER_JARFILE}}\" || printf %s \"@unix_args.txt\" )", + "skip_egg_scripts": false, + "build": { + "memory_limit": 0, + "swap": 0, + "io_weight": 500, + "cpu_limit": 0, + "threads": null, + "disk_space": 0, + "oom_disabled": true + }, + "container": { + "image": "ghcr.io/pterodactyl/yolks:java_8", + "oom_disabled": true, + "requires_rebuild": false + }, + "allocations": { + "force_outgoing_ip": false, + "default": { + "ip": "127.0.0.1", + "port": 25565 + }, + "mappings": { + "127.0.0.1": [ + 25565 + ] + } + }, + "mounts": [], + "egg": { + "id": "a1b2c3d4-5ef6-7g8h-9012-34i5j67k8l9m", + "file_denylist": [] + } + }, + "process_configuration": { + "startup": { + "done": [ + ")! For help, type " + ], + "user_interaction": [], + "strip_ansi": false + }, + "stop": { + "type": "command", + "value": "stop" + }, + "configs": [ + { + "parser": "properties", + "file": "server.properties", + "replace": [ + { + "match": "server-ip", + "replace_with": "0.0.0.0" + }, + { + "match": "server-port", + "replace_with": "25565" + }, + { + "match": "query.port", + "replace_with": "25565" + } + ] + } + ] + } +} +``` + +Sources + +- [app/Http/Controllers/Api/Remote/Servers/ServerDetailsController.php#L35](https://github.com/pterodactyl/panel/blob/v1.11.3/app/Http/Controllers/Api/Remote/Servers/ServerDetailsController.php#L35) + +--- + +### `GET /api/remote/servers/:uuid/install` + +Returns installation information for a server. + +### Responses + +| Code | Description | +| ---- | --------------------------- | +| 200 | The request was successful. | +| 404 | The server was not found. | + +### Response example + +```json +{ + "body": { + "container_image": "openjdk:8-jdk-slim", + "entrypoint": "bash", + "script": "# Installation script here" + } +} +``` + +Sources + +- [app/Http/Controllers/Api/Remote/Servers/ServerInstallController.php#L30](https://github.com/pterodactyl/panel/blob/v1.11.3/app/Http/Controllers/Api/Remote/Servers/ServerInstallController.php#L30) + +--- + +### `POST /api/remote/servers/:uuid/install` + +Updates the installation state of a server. + +### Body + +| Name | Visibility | Type | Description | +| ---------- | ---------- | ------- | -------------------------------------------------------------- | +| successful | required | boolean | Notifies if the server has completed the installation process. | +| reinstall | required | boolean | The state of the server. | + +### Responses + +| Code | Description | +| ---- | --------------------------- | +| 204 | The request was successful. | +| 404 | The server was not found. | + +Sources + +- [app/Http/Controllers/Api/Remote/Servers/ServerInstallController.php#L48](https://github.com/pterodactyl/panel/blob/v1.11.3/app/Http/Controllers/Api/Remote/Servers/ServerInstallController.php#L48) diff --git a/pterodactyl/remote/server_transfer.md b/pterodactyl/remote/server_transfer.md new file mode 100644 index 0000000..3ba8bb0 --- /dev/null +++ b/pterodactyl/remote/server_transfer.md @@ -0,0 +1,33 @@ +### `POST /api/remote/servers/:uuid/transfer/success` + +The daemon notifies the panel about a transfer success. + +### Responses + +| Code | Description | +| ---- | --------------------------------- | +| 204 | The request was successful. | +| 404 | The server was not found. | +| 409 | Server is not being transferred. | + +Sources + +- [app/Http/Controllers/Api/Remote/Servers/ServerTransferController.php#L50](https://github.com/pterodactyl/panel/blob/v1.11.3/app/Http/Controllers/Api/Remote/Servers/ServerTransferController.php#L50) + +--- + +### `POST /api/remote/servers/:uuid/transfer/failure` + +The daemon notifies the panel about a transfer failure. + +### Responses + +| Code | Description | +| ---- | --------------------------------- | +| 204 | The request was successful. | +| 404 | The server was not found. | +| 409 | Server is not being transferred. | + +Sources + +- [app/Http/Controllers/Api/Remote/Servers/ServerTransferController.php#L34](https://github.com/pterodactyl/panel/blob/v1.11.3/app/Http/Controllers/Api/Remote/Servers/ServerTransferController.php#L34) diff --git a/pterodactyl/remote/servers.md b/pterodactyl/remote/servers.md new file mode 100644 index 0000000..0d84ab6 --- /dev/null +++ b/pterodactyl/remote/servers.md @@ -0,0 +1,219 @@ +### `GET /api/remote/servers` + +Lists all servers with their configurations that are assigned to the requesting node. + +### Parameters + +| Name | Visibility | Description | +| --------- | ---------- | ------------------------------ | +| page | optional | The page to list. | +| per_page | optional | The amount of servers to list. | + +### Responses + +| Code | Description | +| ---- | --------------------------- | +| 200 | The request was successful. | + +### Response example + +```json +{ + "data": [ + { + "uuid": "0a123456-bcd7-8901-e234-567fgh890ij1", + "settings": { + "uuid": "0a123456-bcd7-8901-e234-567fgh890ij1", + "meta": { + "name": "My server", + "description": "" + }, + "suspended": false, + "environment": { + "SERVER_JARFILE": "server.jar", + "MC_VERSION": "latest", + "BUILD_TYPE": "recommended", + "FORGE_VERSION": "", + "STARTUP": "java -Xms128M -XX:MaxRAMPercentage=95.0 -Dterminal.jline=false -Dterminal.ansi=true $( [[ ! -f unix_args.txt ]] && printf %s \"-jar {{SERVER_JARFILE}}\" || printf %s \"@unix_args.txt\" )", + "P_SERVER_LOCATION": "home", + "P_SERVER_UUID": "0a123456-bcd7-8901-e234-567fgh890ij1", + "P_SERVER_ALLOCATION_LIMIT": 0 + }, + "invocation": "java -Xms128M -XX:MaxRAMPercentage=95.0 -Dterminal.jline=false -Dterminal.ansi=true $( [[ ! -f unix_args.txt ]] && printf %s \"-jar {{SERVER_JARFILE}}\" || printf %s \"@unix_args.txt\" )", + "skip_egg_scripts": false, + "build": { + "memory_limit": 0, + "swap": 0, + "io_weight": 500, + "cpu_limit": 0, + "threads": null, + "disk_space": 0, + "oom_disabled": true + }, + "container": { + "image": "ghcr.io/pterodactyl/yolks:java_8", + "oom_disabled": true, + "requires_rebuild": false + }, + "allocations": { + "force_outgoing_ip": false, + "default": { + "ip": "192.168.228.1", + "port": 25565 + }, + "mappings": { + "192.168.228.1": [ + 25565 + ] + } + }, + "mounts": [], + "egg": { + "id": "b3e7a6b9-1cc9-4d3e-9372-88b6d96c6b0f", + "file_denylist": [] + } + }, + "process_configuration": { + "startup": { + "done": [ + ")! For help, type " + ], + "user_interaction": [], + "strip_ansi": false + }, + "stop": { + "type": "command", + "value": "stop" + }, + "configs": [ + { + "parser": "properties", + "file": "server.properties", + "replace": [ + { + "match": "server-ip", + "replace_with": "0.0.0.0" + }, + { + "match": "server-port", + "replace_with": "25565" + }, + { + "match": "query.port", + "replace_with": "25565" + } + ] + } + ] + } + } + ], + "links": { + "first": "http://127.0.0.1/api/remote/servers?page=1", + "last": "http://127.0.0.1/api/remote/servers?page=3", + "prev": null, + "next": "http://127.0.0.1/api/remote/servers?page=2" + }, + "meta": { + "current_page": 1, + "from": 1, + "last_page": 3, + "links": [ + { + "url": null, + "label": "« Previous", + "active": false + }, + { + "url": "http://127.0.0.1/api/remote/servers?page=1", + "label": "1", + "active": true + }, + { + "url": "http://127.0.0.1/api/remote/servers?page=2", + "label": "2", + "active": false + }, + { + "url": "http://127.0.0.1/api/remote/servers?page=3", + "label": "3", + "active": false + }, + { + "url": "http://127.0.0.1/api/remote/servers?page=2", + "label": "Next »", + "active": false + } + ], + "path": "http://127.0.0.1/api/remote/servers", + "per_page": 1, + "to": 1, + "total": 3 + } +} +``` + +Sources + +- [https://github.com/pterodactyl/panel/blob/v1.11.3/app/Http/Controllers/Api/Remote/Servers/ServerDetailsController.php#L49](app/Http/Controllers/Api/Remote/Servers/ServerDetailsController.php#L49) + +--- + +### `POST /api/remote/servers/reset` + +Resets the state of all servers on the node to be normal. + +### Responses + +| Code | Description | +| ---- | --------------------------- | +| 204 | The request was successful. | + +Sources + +- [app/Http/Controllers/Api/Remote/Servers/ServerDetailsController.php#L72](https://github.com/pterodactyl/panel/blob/v1.11.3/app/Http/Controllers/Api/Remote/Servers/ServerDetailsController.php#L72) + +--- + +### `POST /api/remote/activity` + +### Body + +| Name | Visibility | Type | Description | +| ----- | ---------- | ------ | -------------------------------------------- | +| data | required | array | An array with all server activity data. | + +### Example Body + +```json +{ + "data": [ + { + "server": "a1bc2345-678d-9e01-2f3g-4hijk5l6m789", + "event": "server:sftp.write", + "timestamp": "1968-01-01T00:00:00.000000000Z", + "metadata": { + "files": [ "/fake.log" ], + }, + "ip": "0.0.0.0", + "user": "abcde1fg-2345-6789-012h-ij34kl5m6789" + } + ] +} +``` + +- `metadata` depends on the event. It can be null, a string, or a json blob with event specific metadata. +- `ip` has to be an IP address or empty string. +- `user` has to be a user UUID or undefined. +- `events` are activity events. You can find a list of them by [clicking here](activity_events.md). + +### Responses + +| Code | Description | +| ---- | ------------------------------------------------ | +| 200 | The response was successful. (no request body) | +| 422 | Incorrect field data. | + +Sources + +- [app/Http/Controllers/Api/Remote/ActivityProcessingController.php#L20](https://github.com/pterodactyl/panel/blob/v1.11.3/app/Http/Controllers/Api/Remote/ActivityProcessingController.php#L20) diff --git a/pterodactyl/remote/sftp.md b/pterodactyl/remote/sftp.md new file mode 100644 index 0000000..d2db68b --- /dev/null +++ b/pterodactyl/remote/sftp.md @@ -0,0 +1,38 @@ +### `POST /api/remote/sftp/auth` + +Authenticate a set of credentials and return the associated server details for a SFTP connection on the daemon. This supports both public key and password based credentials. + +### Body + +| Name | Visibility | Type | Description | +| -------------- | ---------- | ------ | ------------------------------------------------------------------------------------------------- | +| type | optional | string | Determine if the password should check authentication with either the "password" or "public_key". | +| username | required | string | The username of the user attempting to login. | +| password | required | string | The password of the user attempting to login. + +### Responses + +| Code | Description | +| ---- | ---------------------------------------- | +| 200 | The response was successful. | +| 403 | Incorrect credentials. | +| 422 | Missing fields. (ex. username, password) | + +### Response example + +```json +{ + "user": "1abc23de-4567-89f0-ghi1-h2kl345m6nop", + "server": "1a234567-8b9c-01d2-ef3g-45hi67j890kl", + "permissions": [ + "*", + "admin.websocket.errors", + "admin.websocket.install", + "admin.websocket.transfer" + ] +} +``` + +Sources + +- [app/Http/Controllers/Api/Remote/SftpAuthenticationController.php#L34](https://github.com/pterodactyl/panel/blob/v1.11.3/app/Http/Controllers/Api/Remote/SftpAuthenticationController.php#L34)