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
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.
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.
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
Example configuration to enable only the local client interfaces:
Example configuration to enable local client functionality and runners:
netapi_enable_clients for the full list of available client interfaces.
Changes to the Salt master configuration require a restart of the salt-master service. The salt-api service should also be restarted.
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 will have to be adjusted to set the correct username, password and external authentication 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 documentation.