Enabling netapi client interfaces

From Salt's 3006.0 release onwards, all netapi client interfaces are disabled by default.

To enable netapi/salt-api functionality, users should follow the process in this documentation. If the netapi_enable_clients configuration is not added to the Salt master configuration, then the netapi/salt-api will not function.

Breaking change in Salt 3006.0 and above

Users of netapi/salt-api upgrading to Salt 3006.0 must follow the process in this documentation to enable the required netapi client interfaces. If the netapi_enable_clients configuration is not added to the Salt master configuration netapi/salt-api will not function

Steps to enable netapi client interfaces

netapi-enable-clients-select
netapi-enable-clients-update
netapi-enable-clients-restart
netapi-enable-clients-verify

Select client interfaces to enable

Salt's client interfaces provide the ability to execute functions from execution, runner, wheel modules, and via the salt-ssh system.

It is recommended to only enable the client interfaces required to complete the tasks needed to reduce the amount of Salt functionality exposed via the netapi. For example, if the salt-ssh system is not in use, not enabling the ssh client interface will help protect the Salt master from attacks which look to exploit salt-ssh.

The main client interfaces are:

local - run execution modules on minions
local_subset - run execution modules on a subset of minions
runner - run runner modules on master
ssh - run salt-ssh commands
wheel - run wheel modules

The local, runner, and wheel clients also have async variants to run modules asynchronously. See netapi_enable_clients for the complete list.

Most scenarios will require enabling the local client (and potentially its local_subset and local_async variants). The local client is equivalent to the salt command line tool and is required to run execution modules against minions.

Many deployments may also require the ability to call runner functions on the master (for example, where orchestrations are used), but the runner client should only be enabled if this is the case.

As there is not a standard netapi client application, existing users will need to assess which client interfaces are in use. Where an application or tool is making a request to a netapi module, it will usually pass an option indicating which client to use and it should be possible to inspect the source of any tools to understand which client interfaces should be enabled.

For common command line clients, such as pepper they will normally default to using the local client interface unless passed an option to specify a different client interface.

Update Salt master config

Once it has been established which client interfaces will be required or are currently in use, those should be listed in the Salt master config, under the netapi_enable_clients key.

Example configuration to enable only the local client interfaces:

netapi_enable_clients:
  - local
  - local_async
  - local_batch
  - local_subset

Example configuration to enable local client functionality and runners:

netapi_enable_clients:
  - local
  - local_async
  - local_batch
  - local_subset
  - runner
  - runner_async

See netapi_enable_clients for the full list of available client interfaces.

Restart salt-master and salt-api

Changes to the Salt master configuration require a restart of the salt-master service. The salt-api service should also be restarted.

Verify required functionality

Testing that the required functionality is available can be done using curl. It is recommended to also check that client interfaces that are not required are not enabled.

Examples

Examples will have to be adjusted to set the correct username, password and external authentication <acl-eauth> values for the user's system.

Checking that the local client is enabled:

curl -sSKi https://localhost:8000/run \
    -H 'Accept: application/x-yaml' \
    -d client='local' \
    -d tgt='*' \
    -d fun='test.ping' \
    -d username='saltdev' \
    -d password='saltdev' \
    -d eauth='auto'

HTTP/1.1 200 OK
Content-Type: application/x-yaml
Server: CherryPy/18.8.0
Date: Mon, 23 Jan 2023 14:54:58 GMT
Allow: GET, HEAD, POST
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: GET, POST
Access-Control-Allow-Credentials: true
Vary: Accept-Encoding
Content-Length: 25

return:
  - saltdev1: true

Checking that the runner client is not enabled:

curl -sSKi https://localhost:8000/run \
    -H 'Accept: application/x-yaml' \
    -d client='runner' \
    -d fun='test.arg' \
    -d arg='test arg' \
    -d username='saltdev' \
    -d password='saltdev' \
    -d eauth='auto'

HTTP/1.1 400 Bad Request
Content-Type: text/html;charset=utf-8
Server: CherryPy/18.8.0
Date: Mon, 23 Jan 2023 14:59:33 GMT
Allow: GET, HEAD, POST
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: GET, POST
Access-Control-Allow-Credentials: true
Content-Length: 750
Vary: Accept-Encoding
...

Further examples are available in the neatpi modules <all-netapi-modules> documentation.

6 KiB Raw Blame History