From b2efc05a87237fd014db3cc7da009c95d1452a52 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Thu, 18 Dec 2025 12:19:09 -0500 Subject: [PATCH] influxdb3 security cleanup (#6649) * hotfix(influxdb3): fix duplicate menu entry for Enterprise security page Change menu key from influxdb3_core to influxdb3_enterprise. * chore(influxdb3) Security: style and cleanup: intro, requirements, callouts --- content/shared/influxdb3-admin/security.md | 166 ++++++++++++++------- 1 file changed, 115 insertions(+), 51 deletions(-) diff --git a/content/shared/influxdb3-admin/security.md b/content/shared/influxdb3-admin/security.md index 6896e5d4c..f7973d0d5 100644 --- a/content/shared/influxdb3-admin/security.md +++ b/content/shared/influxdb3-admin/security.md @@ -1,23 +1,57 @@ + +{{< product-name >}} includes security features to protect your data and system resources. +When you install using DEB or RPM packages, the default `systemd` unit file configures security sandboxing to isolate the database process from the host system. +This page explains the filesystem layout, sandboxing directives, and how to customize security settings for your environment. + +- [Linux DEB and RPM](#linux-deb-and-rpm) + - [Requirements](#requirements) + - [Filesystem layout](#filesystem-layout) + - [systemd unit in detail](#systemd-unit-in-detail) + - [Default sandbox configuration](#default-sandbox-configuration) + - [Site-specific directives](#site-specific-directives) + - [Tuning the systemd unit](#tuning-the-systemd-unit) + - [systemd references](#systemd-references) + ## Linux DEB and RPM -When installing via DEB/RPM on a `systemd`-enabled system, {{< product-name >}} will run in a sandboxed environment as configured by its `systemd` unit file. The shipped `systemd` unit file assumes the following filesystem layout as provided by the DEB and RPM packaging: +When you install via DEB or RPM on a `systemd`-enabled system, {{< product-name >}} runs in a sandboxed environment configured by the provided `systemd` unit file. -* `/etc/influxdb3`: directory for {{< product-name >}} configuration (by default, `0755` permissions with `influxdb3:influxdb3` ownership; adjust to `0750` permissions if storing sensitive credentials, etc) +### Requirements + +- A `systemd`-enabled Linux system +- `systemd` version 248 or later for full sandbox support (Debian 12+, RHEL 9+, Ubuntu 22.04+) + +> [!Note] +> On older systems, `systemd` logs `Unknown lvalue ''` and starts the service without sandbox protection. + +### Filesystem layout + +The provided unit file assumes the following filesystem layout: + +* `/etc/influxdb3`: directory for {{< product-name >}} configuration (`0755` permissions with `influxdb3:influxdb3` ownership by default) * `/etc/influxdb3/influxdb3-{{< product-key >}}.conf`: TOML configuration file * `/usr/bin/influxdb3`: {{< product-name >}} binary * `/usr/lib/influxdb3/python`: directory containing the embedded interpreter used by the {{< product-name >}} processing engine * `/var/lib/influxdb3`: writable directory for {{< product-name >}} -* `/var/lib/influxdb3/data`: default directory for {{< product-name >}} data files when `object-store` is set to `file` (the installation default for DEB/RPM) +* `/var/lib/influxdb3/data`: default directory for {{< product-name >}} data files when `object-store` is set to `file` (the default for DEB and RPM installations) * `/var/lib/influxdb3/plugins`: default directory for {{< product-name >}} plugin files * `/var/log/influxdb3`: writable directory for logging (unused by default) +> [!Important] +> If you store sensitive credentials in `/etc/influxdb3`, adjust permissions to `0750` to restrict access. ### `systemd` unit in detail -The unit file is self-documenting and can be viewed with: +The unit file is self-documenting. +To view the full systemd configuration for the InfluxDB 3 service (`influxdb3-{{< product-key >}}`), enter the following command: +```bash +systemctl cat influxdb3-{{< product-key >}} ``` -$ systemctl cat influxdb3-{{< product-key >}} + +The output is similar to the following: + +```console # /usr/lib/systemd/system/influxdb3-{{< product-key >}}.service [Unit] Description={{< product-name >}} @@ -28,58 +62,87 @@ Type=simple ... ... ``` -The intent of the default sandboxing is to provide meaningful security without breaking common usage; these security options are enabled by default: +#### Default sandbox configuration -* Basic Security - * `StateDirectory=influxdb3` - writable area relative to `/var/lib` - * `LogsDirectory=influxdb3` - writable area relative to `/var/log` (the unit is configured with `StandardOutput=journal` and `StandardError=journal` by default and will not use this directory) - * `User=influxdb3`, `Group=influxdb3`, `SupplementaryGroups=` - run {{< product-name >}} as the unprivileged `influxdb3:influxdb3` user. {{< product-name >}} does not require any special privileges to run and this should always be set to an unprivileged user - * `UMask=0027` - restrictive default file mode creation mask -* Limiting kernel attack surface - * `SystemCallFilter=@system-service`, `SystemCallArchitectures=native`, `SystemCallFilter=~io_uring_setup keyctl userfaultfd`, and `LockPersonality=true` - basic set of allowed Linux system calls excluding a few unneeded ones that can be abused - * `RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX` - limit allowed address families to those needed for basic functionality (ie, IP networking, DNS resolution, etc). Custom processing engine plugins that need kernel socket of route introspection may need to add `AF_NETLINK` to this list - * `RestrictNamespaces=true` - disallow use of Linux namespaces -* Limiting privileges to disallow gaining or inheriting permissions/capabilities (blocks ICMP `ping`, `passwd`, etc): - * `NoNewPrivileges=true` - * `RestrictSUIDSGID=true` - * `CapabilityBoundingSet=` - * `AmbientCapabilities=` -* Host protection - * `ProtectSystem=strict` - make host files read-only - * `ProtectHome=true` - disallow access to `/home` (tip: put credentials, configuration, etc in `/etc/influxdb3` or somewhere in `/var/lib/influxdb3` instead) - * `PrivateTmp=true` - use separate `/tmp` and `/var/tmp` from host - * `TemporaryFileSystem=/dev/shm:mode=1777` - use separate `/dev/shm` (override with `size=` to limit size too) - * `PrivateDevices=true` - allow only pseudo devices with no host mount propagation - * `ProtectKernelLogs=true` - disallow access to the kernel log ring buffer (needed if `PrivateDevices=false`) - * `PrivateIPC=true` - use separate SysV IPC from host - * `InaccessiblePaths=...` - disallow well-known system and user services' named sockets (needed since `AF_UNIX` is allowed) - * `ProtectProc=invisible` - hide processes not owned by this user (ie, `influxdb3:influxdb3`, see above). This provides strong isolation but means that plugins can't see other processes on the system, which could affect custom processing engine plugins that require this +The default sandbox configuration provides security isolation without breaking common use cases. +The following options are set by default: -While the above provides a lot of security, it leaves out directives that are necessarily site-specific like: +##### Basic Security -* `IPAddressDeny` and `IPAddressAllow` for limiting communications by the database and processing engine to certain IP addresses -* `MemoryHigh`, `MemoryMax`, etc for limiting memory usage (the database process already has configurable controls for memory so this is primarily useful to limit the processing engine) -* `Nice`, `CPUQuota`, `CPUSchedulingPolicy`, `LimitNPROC`, `TasksMax`, etc for limiting CPU usage (the database process already has configurable controls for CPU so this is primarily useful to limit the processing engine) -* `IOWeight`, etc for limiting I/O operations (primarily useful for limiting the processing engine) -* `ReadOnlyPaths`, `ReadWritePaths`, `InaccessiblePaths`, etc to allow/disallow other paths not covered by the default sandbox +Defaults for basic security, such as filesystem and user: -Furthermore, due to a limit in {{% product-name %}} related to socket activation, `PrivateNetwork=true` cannot be used at this time. +- `StateDirectory=influxdb3` - writable area relative to `/var/lib` +- `LogsDirectory=influxdb3` - writable area relative to `/var/log` (the unit is configured with `StandardOutput=journal` and `StandardError=journal` by default and will not use this directory) +- `User=influxdb3`, `Group=influxdb3`, `SupplementaryGroups=` - run {{< product-name >}} as the unprivileged `influxdb3:influxdb3` user. {{< product-name >}} does not require any special privileges to run and this should always be set to an unprivileged user +- `UMask=0027` - restrictive default file mode creation mask -Finally, while the `systemd` unit declares the above directives, `systemd` version 248 (released 2021-03-30 and available in Debian 12+, RHEL 9+, Ubuntu 22.04+) is required to utilize them. On older systems, `systemd` will log `Unknown lvalue ''` (or similar) and start the service normally (but without the protection). +##### Limit kernal attack surface + +Defaults to limit the kernal attack surface: + +- `SystemCallFilter=@system-service`, `SystemCallArchitectures=native`, `SystemCallFilter=~io_uring_setup keyctl userfaultfd`, and `LockPersonality=true` - basic set of allowed Linux system calls excluding a few unneeded ones that can be abused +- `RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX` - limit allowed address families to those needed for basic functionality (such as, IP networking and DNS resolution). Custom processing engine plugins that need kernel socket of route introspection may need to add `AF_NETLINK` to this list +- `RestrictNamespaces=true` - disallow use of Linux namespaces + +##### Limit privileges + +Defaults to limit privileges and disallow gaining or inheriting permissions and capabilities (blocks ICMP `ping`, `passwd`): + +- `NoNewPrivileges=true` +- `RestrictSUIDSGID=true` +- `CapabilityBoundingSet=` +- `AmbientCapabilities=` + +##### Host protection + +Defaults for host protection: + +- `ProtectSystem=strict` - make host files read-only +- `ProtectHome=true` - disallow access to `/home` (tip: put credentials, configuration, etc in `/etc/influxdb3` or somewhere in `/var/lib/influxdb3` instead) +- `PrivateTmp=true` - use separate `/tmp` and `/var/tmp` from host +- `TemporaryFileSystem=/dev/shm:mode=1777` - use separate `/dev/shm` (override with `size=` to limit size too) +- `PrivateDevices=true` - allow only pseudo devices with no host mount propagation +- `ProtectKernelLogs=true` - disallow access to the kernel log ring buffer (needed if `PrivateDevices=false`) +- `PrivateIPC=true` - use separate SysV IPC from host +- `InaccessiblePaths=...` - disallow well-known system and user services' named sockets (needed since `AF_UNIX` is allowed) +- `ProtectProc=invisible` - hide processes not owned by this [user ( `influxdb3:influxdb3`)](#basic-security). This provides strong isolation but means that plugins can't see other processes on the system, which could affect custom processing engine plugins that require this + +#### Site-specific directives + +The default configuration omits directives that depend on your environment--for example, the following directives require tuning based on your deployment requirements and resource constraints: + +- `IPAddressDeny` and `IPAddressAllow` for limiting communications by the database and processing engine to certain IP addresses +- `MemoryHigh` and `MemoryMax` for limiting memory usage (the database process already has configurable controls for memory so this is primarily useful to limit the processing engine) +- `Nice`, `CPUQuota`, `CPUSchedulingPolicy`, `LimitNPROC`, and `TasksMax` for limiting CPU usage (the database process already has configurable controls for CPU so this is primarily useful to limit the processing engine) +- `IOWeight`, etc for limiting I/O operations (primarily useful for limiting the processing engine) +- `ReadOnlyPaths`, `ReadWritePaths`, and `InaccessiblePaths` to allow/disallow other paths not covered by the default sandbox + +> [!Important] +> Due to a limit in {{% product-name %}} related to socket activation, `PrivateNetwork=true` cannot be used at this time. ### Tuning the `systemd` unit -While the shipped `systemd` unit is verified to work with {{% product-name %}} and [official plugins](https://docs.influxdata.com/influxdb3/{{< product-key >}}/plugins/library/official/), you may want to harden the unit further or loosen its restrictions in certain situations. Instead of modifying the `influxdb3-{{< product-key >}}.service` file directly, use `systemctl edit influxdb3-{{< product-key >}}` to add overrides. +While the `systemd` unit is verified to work with {{% product-name %}} and [official plugins](/influxdb3/version/plugins/library/official/), you may want to harden the unit further or loosen its restrictions in certain situations. + +To edit the unit file, enter the following command: + +```bash +systemctl edit influxdb3-{{< product-key >}} +``` + +> [!Note] +> Avoid modifying the `influxdb3-{{< product-key >}}.service` file directly. +> Use `systemctl edit` to add overrides. #### Example: loosen for ProtectProc=default -Suppose a custom plugin needs access to read other processes' information from `/proc`, do: +If a custom plugin needs to read other processes' information from `/proc`: 1. Run `sudo systemctl edit influxdb3-{{< product-key >}}` 2. Edit the file to contain: ``` - ### Editing /etc/systemd/systemd/influxdb3-{{< product-key >}}.service.d/override.conf + ### Editing /etc/systemd/system/influxdb3-{{< product-key >}}.service.d/override.conf ### Anything between here and the comment below will become the new contents of the file [Service] @@ -130,7 +193,7 @@ As an example, to limit communications to only localhost, use `systemctl edit influxdb3-{{< product-key >}}` to add: ``` -### Editing /etc/systemd/systemd/influxdb3-{{< product-key >}}.service.d/override.conf +### Editing /etc/systemd/system/influxdb3-{{< product-key >}}.service.d/override.conf ### Anything between here and the comment below will become the new contents of the file IPAddressDeny=any @@ -144,7 +207,7 @@ Alternatively, to restrict networking to only public IP ranges, use this instead: ``` -### Editing /etc/systemd/systemd/influxdb3-{{< product-key >}}.service.d/override.conf +### Editing /etc/systemd/system/influxdb3-{{< product-key >}}.service.d/override.conf ### Anything between here and the comment below will become the new contents of the file IPAddressDeny=0.0.0.0/32 # 0.0.0.0 treated as 127.0.0.1 @@ -167,12 +230,12 @@ IPAddressDeny=ff00::/8 # IPv6 multicast #### Example: add memory, CPU and I/O control for process node If {{% product-name %}} is configured to start as a standalone processing -engine node (eg, started with `--mode="process"`), then it could utilize -different security directives than the database itself. Eg, consider this +engine node (for example, started with `--mode="process"`), then it could utilize +different security directives than the database itself. For example, consider the following `systemd` override for limiting a processing engine-only node: ``` -### Editing /etc/systemd/systemd/influxdb3-{{< product-key >}}.service.d/override.conf +### Editing /etc/systemd/system/influxdb3-{{< product-key >}}.service.d/override.conf ### Anything between here and the comment below will become the new contents of the file [Service] @@ -204,10 +267,11 @@ IOWeight=50 ### systemd references -The `systemd` documentation has additional information on the above and more: -* [systemd](https://www.freedesktop.org/software/systemd/man/latest/) -* [systemd.service](https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html) -* [systemd.exec](https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html) -* [systemd.resource-control](https://www.freedesktop.org/software/systemd/man/latest/systemd.resource-control.html) +See the `systemd` documentation for additional information: + +- [systemd](https://www.freedesktop.org/software/systemd/man/latest/) +- [systemd.service](https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html) +- [systemd.exec](https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html) +- [systemd.resource-control](https://www.freedesktop.org/software/systemd/man/latest/systemd.resource-control.html)