# MinionFS Backend Walkthrough

Added in version 2014.1.0.

Note

This walkthrough assumes basic knowledge of Salt and `cp.push`. To get up to speed, check out the Salt Walkthrough.

Sometimes it is desirable to deploy a file located on one minion to one or more other minions. This is supported in Salt, and can be accomplished in two parts:

1. Minion support for pushing files to the master (using `cp.push`)

2. The `minionfs` fileserver backend

This walkthrough will show how to use both of these features.

## Enabling File Push

To set the master to accept files pushed from minions, the `file_recv` option in the master config file must be set to `True` (the default is `False`).

    file_recv: True

Note

This change requires a restart of the salt-master service.

## Pushing Files

Once this has been done, files can be pushed to the master using the `cp.push` function:

    salt 'minion-id' cp.push /path/to/the/file

This command will store the file in a subdirectory named `minions` under the master's `cachedir`. On most masters, this path will be `/var/cache/salt/master/minions`. Within this directory will be one directory for each minion which has pushed a file to the master, and underneath that the full path to the file on the minion. So, for example, if a minion with an ID of `dev1` pushed a file `/var/log/myapp.log` to the master, it would be saved to `/var/cache/salt/master/minions/dev1/var/log/myapp.log`.

## Serving Pushed Files Using MinionFS

While it is certainly possible to add `/var/cache/salt/master/minions` to the master's `file_roots` and serve these files, it may only be desirable to expose files pushed from certain minions. Adding `/var/cache/salt/master/minions/<minion-id>` for each minion that needs to be exposed can be cumbersome and prone to errors.

Enter `minionfs`. This fileserver backend will make files pushed using `cp.push` available to the Salt fileserver, and provides an easy mechanism to restrict which minions' pushed files are made available.

### Simple Configuration

To use the `minionfs` backend, add `minionfs` to the list of backends in the `fileserver_backend` configuration option on the master:

    file_recv: True

    fileserver_backend:
      - roots
      - minionfs

Note

`minion` also works here. Prior to the 2018.3.0 release, only `minion` would work.

Also, as described earlier, `file_recv: True` is needed to enable the master to receive files pushed from minions. As always, changes to the master configuration require a restart of the `salt-master` service.

Files made available via `minionfs` are by default located at `salt://<minion-id>/path/to/file`. Think back to the earlier example, in which `dev1` pushed a file `/var/log/myapp.log` to the master. With `minionfs` enabled, this file would be addressable in Salt at `salt://dev1/var/log/myapp.log`.

If many minions have pushed to the master, this will result in many directories in the root of the Salt fileserver. For this reason, it is recommended to use the `minionfs_mountpoint` config option to organize these files underneath a subdirectory:

    minionfs_mountpoint: salt://minionfs

Using the above mountpoint, the file in the example would be located at `salt://minionfs/dev1/var/log/myapp.log`.

### Restricting Certain Minions' Files from Being Available Via MinionFS

A whitelist and blacklist can be used to restrict the minions whose pushed files are available via `minionfs`. These lists can be managed using the `minionfs_whitelist` and `minionfs_blacklist` config options. Click the links for both of them for a detailed explanation of how to use them.

A more complex configuration example, which uses both a whitelist and blacklist, can be found below:

    file_recv: True

    fileserver_backend:
      - roots
      - minionfs

    minionfs_mountpoint: salt://minionfs

    minionfs_whitelist:
      - host04
      - web*
      - 'mail\d+\.domain\.tld'

    minionfs_blacklist:
      - web21

### Potential Concerns

- There is no access control in place to restrict which minions have access to files served up by `minionfs`. All minions will have access to these files.

- Unless the `minionfs_whitelist` and/or `minionfs_blacklist` config options are used, all minions which push files to the master will have their files made available via `minionfs`.