community.general.nosh – Manage services with nosh

Note

This plugin is part of the community.general collection (version 4.2.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.nosh.

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
string / 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
string
    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

Examples

- name: Start dnscache if not running
  community.general.nosh: name=dnscache state=started

- name: Stop mpd, if running
  community.general.nosh: name=mpd state=stopped

- name: Restart unbound or start it if not already running
  community.general.nosh:
    name: unbound
    state: restarted

- name: Reload fail2ban or start it if not already running
  community.general.nosh:
    name: fail2ban
    state: reloaded

- name: Disable nsd
  community.general.nosh: name=nsd enabled=no

- name: For package installers, set nginx running state according to local enable settings, preset and reset
  community.general.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
  community.general.nosh: name=reboot state=started

- name: Using conditionals with the module facts
  tasks:
    - name: Obtain information on tinydns service
      community.general.nosh: name=tinydns
      register: result

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

    - name: Fail if service is running
      ansible.builtin.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 / elements=string
success
Sample:
['/etc/service-bundles/targets/basic', '../sshdgenkeys', 'log']
 
Before
list / elements=string
success
Sample:
['/etc/service-bundles/targets/shutdown']
 
Conflicts
list / elements=string
success
Sample:
[]
 
DaemontoolsEncoreState
string
success
Sample:
running
 
DaemontoolsState
string
success
Sample:
up
 
Enabled
boolean
success
Sample:
True
 
LogService
string
success
Sample:
 
MainPID
integer
success
Sample:
661
 
Paused
boolean
success
Sample:
False
 
ReadyAfterRun
boolean
success
Sample:
False
 
RemainAfterExit
boolean
success
Sample:
False
 
Required-By
list / elements=string
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 / elements=string
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 / elements=string
success
Sample:
['/etc/service-bundles/targets/server', '/etc/service-bundles/targets/sockets']
 
Wants
list / elements=string
success
Sample:
['/etc/service-bundles/targets/basic', '../sshdgenkeys']
user
boolean
success
whether the user-level service manager is called



Authors

  • Thomas Caravia (@tacatac)