# nosh – Manage services with nosh

New in version 2.5.

- Synopsis
- Requirements
- Parameters
- Notes
- Examples
- Return Values
- Status

## Synopsis

- Control running and enabled state for system-wide or user services.
- BSD and Linux systems are supported.

## Requirements

The below requirements are needed on the host that executes this module.

- A system with an active nosh service manager, see Notes for further information.

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---

enabled
boolean

Choices:
- no
- yes

Enable or disable the service, independently of `*.preset` file preference or running state. Mutually exclusive with preset. Will take effect prior to state=reset.

name - / required |  | Name of the service to manage.

preset
boolean

Choices:
- no
- yes

Enable or disable the service according to local preferences in *.preset files. Mutually exclusive with enabled. Only has an effect if set to true. Will take effect prior to state=reset.

state
-

Choices:
- started
- stopped
- reset
- restarted
- reloaded

`started`/`stopped` are idempotent actions that will not run commands unless necessary. `restarted` will always bounce the service. `reloaded` will send a SIGHUP or start the service. `reset` will start or stop the service according to whether it is enabled or not.

user
boolean

Choices:
- no ←
- yes

Run system-control talking to the calling user's service manager, rather than the system-wide service manager.

## Notes

Note

- Information on the nosh utilities suite may be found at https://jdebp.eu/Softwares/nosh/.

## Examples

    - name: start dnscache if not running
      nosh: name=dnscache state=started

    - name: stop mpd, if running
      nosh: name=mpd state=stopped

    - name: restart unbound or start it if not already running
      nosh:
        name: unbound
        state: restarted

    - name: reload fail2ban or start it if not already running
      nosh:
        name: fail2ban
        state: reloaded

    - name: disable nsd
      nosh: name=nsd enabled=no

    - name: for package installers, set nginx running state according to local enable settings, preset and reset
      nosh: name=nginx preset=True state=reset

    - name: reboot the host if nosh is the system manager, would need a "wait_for*" task at least, not recommended as-is
      nosh: name=reboot state=started

    - name: using conditionals with the module facts
      tasks:
        - name: obtain information on tinydns service
          nosh: name=tinydns
          register: result

        - name: fail if service not loaded
          fail: msg="The {{ result.name }} service is not loaded"
          when: not result.status

        - name: fail if service is running
          fail: msg="The {{ result.name }} service is running"
          when: result.status and result.status['DaemontoolsEncoreState'] == "running"

## Return Values

Common return values are documented here, the following are the fields unique to this module:

Key | Returned | Description
--- | --- | ---
enabled boolean | success | whether the service is enabled at system bootstrap Sample: True
name string | success | name used to find the service Sample: sshd
preset boolean | success | whether the enabled status reflects the one set in the relevant `*.preset` file Sample: False
service_path string | success | resolved path for the service Sample: /var/sv/sshd
state string | if state option is used | service process run state, `None` if the service is not loaded and will not be started Sample: reloaded
status complex | success | a dictionary with the key=value pairs returned by `system-control show-json` or `None` if the service is not loaded
| After list | success | Sample: ['/etc/service-bundles/targets/basic', '../sshdgenkeys', 'log']
| Before list | success | Sample: ['/etc/service-bundles/targets/shutdown']
| Conflicts list | success | Sample: []
| DaemontoolsEncoreState string | success | Sample: running
| DaemontoolsState string | success | Sample: up
| Enabled boolean | success | Sample: True
| LogService string | success | Sample: ../cyclog@sshd
| MainPID integer | success | Sample: 661
| Paused boolean | success | Sample: False
| ReadyAfterRun boolean | success | Sample: False
| RemainAfterExit boolean | success | Sample: False
| Required-By list | success | Sample: []
| RestartExitStatusCode integer | success | Sample: 0
| RestartExitStatusNumber integer | success | Sample: 0
| RestartTimestamp integer | success | Sample: 4611686019935648081
| RestartUTCTimestamp integer | success | Sample: 1508260140
| RunExitStatusCode integer | success | Sample: 0
| RunExitStatusNumber integer | success | Sample: 0
| RunTimestamp integer | success | Sample: 4611686019935648081
| RunUTCTimestamp integer | success | Sample: 1508260140
| StartExitStatusCode integer | success | Sample: 1
| StartExitStatusNumber integer | success | Sample: 0
| StartTimestamp integer | success | Sample: 4611686019935648081
| StartUTCTimestamp integer | success | Sample: 1508260140
| StopExitStatusCode integer | success | Sample: 0
| StopExitStatusNumber integer | success | Sample: 0
| Stopped-By list | success | Sample: ['/etc/service-bundles/targets/shutdown']
| StopTimestamp integer | success | Sample: 4611686019935648081
| StopUTCTimestamp integer | success | Sample: 1508260140
| Timestamp integer | success | Sample: 4611686019935648081
| UTCTimestamp integer | success | Sample: 1508260140
| Want string | success | Sample: nothing
| Wanted-By list | success | Sample: ['/etc/service-bundles/targets/server', '/etc/service-bundles/targets/sockets']
| Wants list | success | Sample: ['/etc/service-bundles/targets/basic', '../sshdgenkeys']
user boolean | success | whether the user-level service manager is called

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]

### Authors

- Thomas Caravia (@tacatac)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.