openapi: 3.2.0 info: title: Weidmueller Syslog API version: 1.5.0-next contact: name: Weidmüller license: name: MIT identifier: MIT description: 'Operations tagged syslog across 2 of this provider''s published API definitions: administration-openapi.yaml, weidmueller-administration-openapi.yml. Each path carries the servers of the definition it was published in.' servers: - url: /u-os-adm/api/v1 tags: - name: Syslog description: API for syslog forwarding configuration paths: /syslog/certificates: get: tags: - Syslog summary: Get all uploaded certificates description: Returns all certificates organized by type with their content. operationId: get_certificates responses: '200': description: Certificate store content: application/json: schema: $ref: '#/components/schemas/Certificates' default: description: Common HTTP Error codes may be thrown by this method, such as 400, 401, 403, 404, 412, 422 or 500. See body for detailed error info. content: application/problem+json: schema: $ref: '#/components/schemas/HttpErrorPayload' security: - OAuth2: - u-os-adm.syslog.readonly - OAuth2: - u-os-adm.syslog.readwrite put: tags: - Syslog summary: Set all certificates description: 'Replaces the entire certificate store. Any previously uploaded certificate not included in the request will be deleted. To ensure that certificates are unused after deletion, please reboot the device. Deleting a currently used certificate results in an invalid syslog configuration. **Certificate types:** - `server-ca`: CA certificate to verify the syslog server - `client-cert`: Client certificate for mTLS authentication - `client-key`: Client private key for mTLS authentication' operationId: set_certificates requestBody: content: application/json: schema: $ref: '#/components/schemas/Certificates' required: true responses: '200': description: Certificates applied successfully '400': description: Invalid certificate data content: application/problem+json: schema: $ref: '#/components/schemas/HttpErrorPayload' default: description: Common HTTP Error codes may be thrown by this method, such as 400, 401, 403, 404, 412, 422 or 500. See body for detailed error info. content: application/problem+json: schema: $ref: '#/components/schemas/HttpErrorPayload' security: - OAuth2: - u-os-adm.syslog.readwrite patch: tags: - Syslog summary: Partially update certificates description: 'Applies a patch to the certificate store using JSON Merge Patch semantics: - **Absent type**: no changes to that category - **Entry with content**: add or overwrite that certificate - **Entry set to `null`**: delete that certificate To ensure that certificates are unused after deletion, please reboot the device. Deleting a currently used certificate results in an invalid syslog configuration. Example — add a new server CA and delete an old one: ```json { "server-ca": { "new-ca.pem": { "content": "-----BEGIN CERTIFICATE-----\n..." }, "old-ca.pem": null } } ```' operationId: patch_certificates requestBody: content: application/json: schema: $ref: '#/components/schemas/PartialCertificates' required: true responses: '200': description: Certificates updated successfully '400': description: Invalid certificate data content: application/problem+json: schema: $ref: '#/components/schemas/HttpErrorPayload' default: description: Common HTTP Error codes may be thrown by this method, such as 400, 401, 403, 404, 412, 422 or 500. See body for detailed error info. content: application/problem+json: schema: $ref: '#/components/schemas/HttpErrorPayload' security: - OAuth2: - u-os-adm.syslog.readwrite servers: - url: /u-os-adm/api/v1 /syslog/config: get: tags: - Syslog summary: Get syslog forwarding configuration description: Returns the current configuration for syslog forwarding. operationId: get_config responses: '200': description: Syslog forwarding configuration content: application/json: schema: $ref: '#/components/schemas/SyslogConfig' default: description: Common HTTP Error codes may be thrown by this method, such as 400, 401, 403, 404, 412, 422 or 500. See body for detailed error info. content: application/problem+json: schema: $ref: '#/components/schemas/HttpErrorPayload' security: - OAuth2: - u-os-adm.syslog.readonly - OAuth2: - u-os-adm.syslog.readwrite put: tags: - Syslog summary: Set syslog forwarding configuration description: Updates the syslog forwarding configuration with the provided settings. operationId: set_config requestBody: content: application/json: schema: $ref: '#/components/schemas/SyslogConfig' required: true responses: '200': description: Configuration applied successfully '400': description: Invalid configuration content: application/problem+json: schema: $ref: '#/components/schemas/HttpErrorPayload' default: description: Common HTTP Error codes may be thrown by this method, such as 400, 401, 403, 404, 412, 422 or 500. See body for detailed error info. content: application/problem+json: schema: $ref: '#/components/schemas/HttpErrorPayload' security: - OAuth2: - u-os-adm.syslog.readwrite servers: - url: /u-os-adm/api/v1 /syslog/state: get: tags: - Syslog summary: Get syslog forwarding service state description: 'Returns the runtime status of the syslog forwarding service and summary information about the current configuration.' operationId: get_state responses: '200': description: Syslog forwarding service state content: application/json: schema: $ref: '#/components/schemas/SyslogState' default: description: Common HTTP Error codes may be thrown by this method, such as 400, 401, 403, 404, 412, 422 or 500. See body for detailed error info. content: application/problem+json: schema: $ref: '#/components/schemas/HttpErrorPayload' security: - OAuth2: - u-os-adm.syslog.readonly - OAuth2: - u-os-adm.syslog.readwrite servers: - url: /u-os-adm/api/v1 components: schemas: SyslogLevel: type: string description: Syslog severity levels as defined in RFC 5424. enum: - EMERG - ALERT - CRIT - ERR - WARNING - NOTICE - INFO - DEBUG SyslogConfig: type: object description: Main configuration for syslog forwarding. required: - enabled - outputs properties: enabled: type: boolean description: Whether syslog forwarding is enabled. If false, the service is stopped. outputs: type: object description: 'Map of output name to output configuration. Output names must be 1-32 characters, containing only lowercase letters, numbers, and hyphens. Cannot start or end with a hyphen.' additionalProperties: $ref: '#/components/schemas/SyslogOutputConfig' propertyNames: type: string example: my-log-server: destination: format: RFC5424 host: 192.168.1.123 port: 6514 tls: mode: ENABLED server_ca: ca: my-corp-ca.pem mode: VERIFY_WITH_CA transport: TCP filter: facilities: - AUTH identifiers: - sudo - kernel levels: - ERR - WARNING units: - nginx.service ServerCaVerifyWithCa: type: object description: 'Verify the server''s certificate using a custom CA certificate. The CA certificate must be uploaded via PUT /syslog/certificates.' required: - mode - ca properties: ca: type: string description: Name of the CA certificate file. example: my-corp-ca.pem mode: type: string enum: - VERIFY_WITH_CA TlsEnabledWithMtls: type: object required: - mode - server_ca - client_cert - client_key properties: client_cert: type: string description: 'Name of the client certificate file. Must be uploaded via the certificates endpoint.' example: device.pem client_key: type: string description: 'Name of the client private key file. Must be uploaded via the certificates endpoint.' example: device-key.pem mode: type: string enum: - ENABLED_WITH_MTLS server_ca: $ref: '#/components/schemas/ServerCa' SyslogFacility: type: string description: Standard syslog facilities as defined in RFC 5424. enum: - KERN - USER - MAIL - DAEMON - AUTH - SYSLOG - LPR - NEWS - UUCP - CRON - AUTHPRIV - FTP - NTP - AUDIT - ALERT - CLOCK - LOCAL0 - LOCAL1 - LOCAL2 - LOCAL3 - LOCAL4 - LOCAL5 - LOCAL6 - LOCAL7 TlsEnabled: type: object description: TLS is enabled with the given settings. required: - mode - server_ca properties: mode: type: string enum: - ENABLED server_ca: $ref: '#/components/schemas/ServerCa' description: Server certificate verification mode. ServerCa: oneOf: - $ref: '#/components/schemas/ServerCaVerify' - $ref: '#/components/schemas/ServerCaVerifyWithCa' - $ref: '#/components/schemas/ServerCaNoVerify' description: Server certificate verification configuration. ServerCaNoVerify: type: object description: Do not verify the server's certificate (insecure, use only for testing). required: - mode properties: mode: type: string enum: - NO_VERIFY Certificates: type: object description: 'All certificates organized by type. Each certificate type maps certificate names (keys) to their entries.' required: - server_ca - client_cert - client_key properties: client_cert: type: object description: Client certificates for mutual TLS authentication. additionalProperties: $ref: '#/components/schemas/CertificateEntry' propertyNames: type: string client_key: type: object description: Client private keys for mutual TLS authentication. additionalProperties: $ref: '#/components/schemas/CertificateEntry' propertyNames: type: string server_ca: type: object description: CA certificates for verifying the syslog server's identity. additionalProperties: $ref: '#/components/schemas/CertificateEntry' propertyNames: type: string example: client_cert: device.pem: content: '-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----' client_key: device-key.pem: content: M15UP3RS5CR3T server_ca: my-ca.pem: content: '-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----' SyslogState: type: object description: Runtime state of the syslog forwarding service. required: - status properties: outputs: type: object description: 'Per-output health information. Only populated when the service is active and the monitoring API is reachable.' additionalProperties: $ref: '#/components/schemas/OutputState' propertyNames: type: string status: $ref: '#/components/schemas/ServiceStatus' description: Current service status from systemd. example: outputs: audit-logs: reachable: CONNECTED kernel-logs: reachable: ERROR my-app-logs: reachable: PENDING status: ACTIVE Transport: type: string description: Transport protocol for syslog. TLS is configured separately. enum: - TCP - UDP ServerCaVerify: type: object description: Verify the server's certificate using the system's CA certificate store. required: - mode properties: mode: type: string enum: - VERIFY PartialCertificates: type: object description: "All certificates organized by type.\n\n Each certificate type maps certificate names (keys) to their entries. (PATCH)" properties: client_cert: type: object description: Client certificates for mutual TLS authentication. additionalProperties: true client_key: type: object description: Client private keys for mutual TLS authentication. additionalProperties: true server_ca: type: object description: CA certificates for verifying the syslog server's identity. additionalProperties: true OutputState: type: object description: Health information for a single syslog output. required: - reachable properties: reachable: $ref: '#/components/schemas/OutputReachability' description: "Reachability status of the output destination.\n\n- `connected` — The output has successfully sent its most recent batch of logs.\n- `error` — The output is experiencing delivery failures and is currently retrying.\n- `pending` — Reachability cannot be determined yet, because no logs have been\n attempted to be sent so far (e.g. just started or filter-config filtered out all logs)." ServiceStatus: type: string description: Systemd service status. enum: - ACTIVE - INACTIVE - FAILED - ACTIVATING - DEACTIVATING - UNKNOWN SyslogOutputConfig: type: object description: 'A single syslog output destination with its filter criteria. The output name (map key) must be 1-32 characters, containing only lowercase letters, numbers, and hyphens. Cannot start or end with a hyphen.' required: - destination - filter properties: destination: $ref: '#/components/schemas/SyslogDestination' description: The destination server configuration. filter: $ref: '#/components/schemas/SyslogFilter' description: Filter criteria - which logs to send to this output. HttpErrorPayload: type: object description: 'Common error payload structure for HTTP responses. Based on [RFC 9457](https://datatracker.ietf.org/doc/html/rfc9457)' required: - type - title - status properties: detail: type: - string - 'null' description: Optional details about the error example: 'Low Level OS Error #1234' instance: type: - string - 'null' format: uri-reference description: A human-readable explanation specific to this occurrence of the problem example: null status: type: integer format: int32 description: The HTTP status code generated by the origin server for this occurrence of the problem example: 500 maximum: 599 minimum: 100 title: type: string description: Human-readable error message. example: Something went wrong in the backend. type: type: string format: uri-reference description: 'A URI reference that identifies the problem type The last part of the URI is always a `ErrorId`' example: /u-os-adm/api/v1/errors/set-security-settings TlsDisabled: type: object description: TLS is disabled (plain-text transport). required: - mode properties: mode: type: string enum: - DISABLED SyslogFormat: type: string description: Syslog message format standard. enum: - RFC5424 - RFC3164 OutputReachability: type: string description: Reachability status of a syslog output destination. enum: - CONNECTED - ERROR - PENDING CertificateEntry: type: object description: A single certificate entry. required: - content properties: content: type: string description: PEM-encoded certificate or key content. TlsConfig: oneOf: - $ref: '#/components/schemas/TlsDisabled' - $ref: '#/components/schemas/TlsEnabled' - $ref: '#/components/schemas/TlsEnabledWithMtls' description: 'TLS configuration for encrypted syslog transport. Certificates are managed separately via the certificates endpoint.' SyslogDestination: type: object description: Destination server configuration. required: - host - port - transport - tls - format properties: format: $ref: '#/components/schemas/SyslogFormat' description: Syslog message format. host: type: string description: Server hostname or IP address. example: 192.168.1.100 port: type: integer format: int32 description: Server port number (514 for plain syslog, 6514 for TLS is common). example: 6514 minimum: 0 tls: $ref: '#/components/schemas/TlsConfig' description: TLS configuration. Determines whether TLS encryption is used (TCP only). transport: $ref: '#/components/schemas/Transport' description: 'Transport protocol: TCP or UDP.' SyslogFilter: type: object description: 'Syslog filter criteria. Filtering uses systemd journal''s native logic: - Within a field: values are OR''d (e.g., level=err OR level=warning) - Across fields: conditions are AND''d (e.g., level=err AND facility=auth) - Empty fields match everything' required: - levels - facilities - units - identifiers properties: facilities: type: array items: $ref: '#/components/schemas/SyslogFacility' description: 'Syslog facilities to include. Standard RFC 5424 facility codes. If empty, logs from all facilities are included. Your services can use local0-local7 for custom categorization.' identifiers: type: array items: type: string description: 'Specific `SYSLOG_IDENTIFIER` values to include (e.g. ''kernel''). Each identifier must: - Be at most 128 characters - Contain only: ASCII letters (a-z, A-Z), digits (0-9), ''-'', ''_'', ''.'' - Not be empty If empty, logs from all identifiers are included.' example: - sudo - kernel levels: type: array items: $ref: '#/components/schemas/SyslogLevel' description: 'Log severity levels to include. Only logs with these exact levels are forwarded. If empty, logs of all severity levels are included.' units: type: array items: type: string description: "Specific systemd units to include.\n\nEach unit name must:\n- Be at most 255 characters\n- Contain only: ASCII letters (a-z, A-Z), digits (0-9), ':', '-', '_', '.', '@'\n- End with a valid unit suffix: .service, .socket, .device, .mount,\n .automount, .swap, .target, .path, .timer, .slice, or .scope\n\nExamples: \"nginx.service\", \"sshd.socket\", \"user@1000.service\"\n\nIf empty, logs from all units are included." example: - nginx.service - fluent-bit.service securitySchemes: OAuth2: type: oauth2 flows: clientCredentials: tokenUrl: /oauth2/token scopes: u-os-adm.firewall.readonly: Read access for firewall endpoints u-os-adm.firewall.readwrite: Read and write access for firewall endpoints u-os-adm.logging.readonly: Read access for logging endpoints u-os-adm.network.readonly: Read access for network endpoints u-os-adm.network.readwrite: Read and write access for network endpoints u-os-adm.realtime.readonly: Read access for realtime endpoints u-os-adm.realtime.readwrite: Read and write access for realtime endpoints u-os-adm.recovery.readwrite: Read and write access for recovery endpoints u-os-adm.security.readonly: Read access for security endpoints u-os-adm.security.readwrite: Read and write access for security endpoints u-os-adm.serial-interfaces.readonly: Read access for serial interface configuration endpoints u-os-adm.serial-interfaces.readwrite: Read and write access for serial interface configuration endpoints u-os-adm.syslog.readonly: Read access for syslog endpoints u-os-adm.syslog.readwrite: Read and write access for syslog endpoints u-os-adm.system.readonly: Read access for system endpoints u-os-adm.system.readwrite: Read and write access for system endpoints u-os-adm.time.readonly: Read access for time settings endpoints u-os-adm.time.readwrite: Read and write access for time settings endpoints u-os-adm.update.readonly: Read access for update endpoints u-os-adm.update.readwrite: Read and write access for update endpoints description: The HTTP API uses the OAuth2 client credentials flow. x-refined-from: - administration-openapi.yaml - weidmueller-administration-openapi.yml