# ansible.builtin.systemd_service
Controls [systemd](../../../linux/Systemd.md) units (services, timers, and so on) on remote hosts.

## Parameter
| Parameter         | Type                                                | Default  | Description                                                                                                                                                                                                                                                                                                |
| ----------------- | --------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **daemon_reload** | boolean                                             | false    | Run daemon-reload before doing any other operations, to make sure systemd has read any changes.                                                                                                                                                                                                            |
| **enabled**       | boolean                                             | -        | Whether the unit should start on boot. **At least one of state and enabled are required.**                                                                                                                                                                                                                 |
| **force**         | boolean                                             | -        | Whether to override existing symlinks.                                                                                                                                                                                                                                                                     |
| **masked**        | boolean                                             | -        | Whether the unit should be masked or not, a masked unit is impossible to start.                                                                                                                                                                                                                            |
| **name**          | string                                              | -        | Name of the unit. This parameter takes the name of exactly one unit to work with. When no extension is given, it is implied to a `.service` as systemd.                                                                                                                                                    |
| **scope**         | "system"<br>"user"<br>"global"                      | "system" | Run systemctl within a given service manager scope, either as the default system scope `system`, the current user’s scope `user`, or the scope of all users `global`. For systemd to work with ‘user’, the executing user must have its own instance of dbus started and accessible (systemd requirement). |
| **state**         | "reloaded"<br>"restarted"<br>"started"<br>"stopped" | -        | `started`/`stopped` are idempotent actions that will not run commands unless necessary. `restarted` will always bounce the unit. `reloaded` will always reload.                                                                                                                                                                                                                                                                                                           |

## Return Values
| Value      | Type       | When    | Description                                                           |
| ---------- | ---------- | ------- | --------------------------------------------------------------------- |
| **status** | dictionary | success | A dictionary with the key=value pairs returned from `systemctl show`. |

## Examples
```yaml
- name: Make sure a service unit is running
  ansible.builtin.systemd:
    state: started
    name: httpd

- name: Stop service cron on debian, if running
  ansible.builtin.systemd:
    name: cron
    state: stopped

- name: Restart service cron on centos, in all cases, also issue daemon-reload to pick up config changes
  ansible.builtin.systemd:
    state: restarted
    daemon_reload: true
    name: crond

- name: Reload service httpd, in all cases
  ansible.builtin.systemd:
    name: httpd.service
    state: reloaded

- name: Enable service httpd and ensure it is not masked
  ansible.builtin.systemd:
    name: httpd
    enabled: true
    masked: no

- name: Enable a timer unit for dnf-automatic
  ansible.builtin.systemd:
    name: dnf-automatic.timer
    state: started
    enabled: true

- name: Just force systemd to reread configs (2.4 and above)
  ansible.builtin.systemd:
    daemon_reload: true

- name: Just force systemd to re-execute itself (2.8 and above)
  ansible.builtin.systemd:
    daemon_reexec: true

- name: Run a user service when XDG_RUNTIME_DIR is not set on remote login
  ansible.builtin.systemd:
    name: myservice
    state: started
    scope: user
  environment:
    XDG_RUNTIME_DIR: "/run/user/{{ myuid }}"
```