Skip to main content
On Linux the Miru Agent runs as the miru system user and needs specific file system permissions in the two cases where it touches files on your devices:
  • Configs — writes config instances to disk when it deploys a release
  • Data uploads — reads files to upload them to your bucket
This page covers the agent’s default permissions and how to grant file system access.

​
Configs

Default config path During installation, the agent creates and owns /srv/miru. The directory is owned by the miru user and group (miru:miru), with mode 0755. The agent creates configs inside it with mode 0644 and subdirectories with mode 0755. Deploying configs to /srv/miru requires no additional configuration. The agent holds write access and all applications can read the configs.
/srv/miru is world-readable. For stricter security configurations, consider using a custom config path.
Custom config paths The Miru Agent also supports writing configs to arbitrary file system paths. Some examples include:
  • /etc/myapp/configs/mobility.json
  • /home/myapp/configs/communication.yaml
  • /var/lib/myapp/configs/safety.yaml
You must use Miru Agent v0.8.0 or later to deploy configurations to a path that does not begin with /srv/miru/config_instances/.
To enable the agent to write to these paths, grant the required permissions outlined below. Otherwise, the agent will receive a permission denied error from the operating system.

​
Required permissions

To write to a given file, the miru user requires specific permissions to
  1. The file itself
  2. The directories along the path to the file
Let’s consider the file /var/lib/myapp/configs/planning.yaml as an example. The required read and write permissions to grant the miru user access to this file are shown in the table below. To write to a given file, the miru user requires the following Unix permissions:
  1. Read (r) and write (w) access to the file itself
    • r (read) is required to read the file contents.
    • w (write) is required to write the file contents.
    If the file does not yet exist, you can ignore this permission. The agent will create it with the appropriate permissions.
  2. Read (r), write (w), and execute (x) access to the file’s parent directory
    • r (read) is required to scan files within the directory.
    • w (write) is required to create/replace directory entries (e.g., temp file + rename for atomic writes).
    • x (execute/search) is required to access files within the directory.
  3. Execute (x) access to all directories along the path to the file
    • x (execute) is required to access directories within the path to the file.
    Many directories, such as /var/lib, are world-readable by default and need no special permissions. Other directories, such as /home/myapp, will not grant miru user access by default and must be specifically configured.
To grant these permissions, follow the instructions in Granting access.

​
Data uploads

To upload files from disk, the agent reads the files matched by a file rule’s source.glob and streams them to your bucket. You must grant the required permissions outlined below. Otherwise, the agent will receive a permission denied error from the operating system.

​
Required permissions

To read a file for upload, the miru user requires specific permissions to
  1. The file itself
  2. The directories along the path to the file
Let’s consider a file rule whose source.glob is /var/log/robot/*.log, matching the file /var/log/robot/app.log. The required permissions to grant the miru user access to this file are shown in the table below. To read a given file, the miru user requires the following Unix permissions:
  1. Read (r) access to the file itself
    • r (read) is required to read the file contents for upload.
  2. Read (r) and execute (x) access to the file’s parent directory
    • r (read) is required to list the directory and match files against the glob.
    • x (execute/search) is required to open files within the directory.
  3. Execute (x) access to all directories along the path to the file
    • x (execute) is required to traverse directories within the path to the file.
    Many directories, such as /var/log, are world-readable and executable by default and need no special permissions. Others, such as /home/myapp, will not grant miru user access by default and must be specifically configured.
To grant these permissions, follow the instructions in Granting access. Uploads are read-only — the miru user does not need write access to the source files, unless the rule also deletes them, covered next.

​
Deleting local files

If a file rule has a retention block, the agent removes each matching file once its retention guarantee ends. Deleting a file requires write (w) access to its parent directory (to remove the directory entry), so grant the miru user r, w, and x on the directory in that case: To grant these permissions, follow the instructions in Granting access.

​
Granting access

There are two common methods for granting a user (the miru user) access to a given path:
  1. Standard Unix permissions - basic owner/group/other mode bits on a file or directory
  2. ACLs - per-user or per-group access rules beyond mode bits
Since standard Unix permissions are the most familiar, you’ll likely find them simpler to work with. We recommend starting here. However, you may find that changing ownership or group is not possible or desirable. In this case, ACLs may be a better fit. ACLs provide flexibility by allowing you to retain existing permissions for a given path while granting the miru user or group the required permissions.

​
Standard Unix permissions

For standard Unix permissions, there are three approaches, in order of preference:
  1. Add miru to a group that already has access
  2. Grant the miru group the appropriate permissions
  3. Transfer ownership to the miru user
When the target files already belong to a group with the access you need — common for upload sources produced by another application — adding miru to that group is the least invasive option. We recommend starting there. Otherwise, grant the miru group access directly.

​
Add miru to an existing group

Add the miru user to a group that already has the required access, so it inherits that group’s permissions without touching the path:
The agent only picks up a new group when it starts, so restart it after adding the group:

​
Set the group or owner

If no group already grants the access you need, set the path’s group to miru (recommended) or transfer ownership to miru. Files
Replace path="/path/to/file.json" with the actual file path
Directories
Replace path="/path/to/dir" with the actual directory path

​
ACLs

When you cannot change the ownership or the group of a path (e.g., a directory shared between multiple services), use POSIX Access Control Lists (ACLs) for fine-grained permission control. ACLs require the acl package. If setfacl is not available, install it with:
Files Grant the miru user access to a file.
Replace /path/to/file.json with the actual file path
Directories Grant the miru user access to a directory.
Replace /path/to/dir with the actual directory path
Last modified on October 9, 2026