# containers.podman.podman_generate_systemd module – Generate systemd unit from a pod or a container

Note

This module is part of the containers.podman collection (version 1.20.0).

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 containers.podman`. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: `containers.podman.podman_generate_systemd`.

## Synopsis

- Generate systemd .service unit file(s) from a pod or a container

- Support Ansible check mode

## Requirements

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

- Podman installed on target host

## Parameters

Parameter | Comments
--- | ---

after

list / elements=string

Add the systemd unit after (`After=`) option, that ordering dependencies between the list of dependencies and this service.

This option may be specified more than once.

User-defined dependencies will be appended to the generated unit file

But any existing options such as needed or defined by default (e.g. `online.target`) will not be removed or overridden.

Only with Podman 4.0.0 and above

container_prefix string | Set the systemd unit name prefix for containers. If not set, use the default defined by podman, `container`. Refer to podman-generate-systemd(1) man page for more information.
dest path | Destination of the generated systemd unit file(s). Use `/etc/systemd/system` for the system-wide systemd instance. Use `/etc/systemd/user` or `~/.config/systemd/user` for use with per-user instances of systemd.
env dictionary | Set environment variables to the systemd unit files. Keys are the environment variable names, and values are the environment variable values Only with Podman 4.3.0 and above
executable string | `Podman` executable name or full path Default: `"podman"`

force

boolean

Replace the systemd unit file(s) even if it already exists.

This works with dest option.

Choices:

- `false` ← (default)

- `true`

name string / required | Name of the pod or container to export

new

boolean

Generate unit files that create containers and pods, not only start them.

Refer to podman-generate-systemd(1) man page for more information.

Choices:

- `false` ← (default)

- `true`

no_header

boolean

Do not generate the header including meta data such as the Podman version and the timestamp.

Choices:

- `false` ← (default)

- `true`

pod_prefix string | Set the systemd unit name prefix for pods. If not set, use the default defined by podman, `pod`. Refer to podman-generate-systemd(1) man page for more information.
requires list / elements=string | Set the systemd unit requires (Requires=) option. Similar to wants, but declares a stronger requirement dependency. Only with Podman 4.0.0 and above

restart_policy

string

Restart policy of the service

Choices:

- `"no-restart"`

- `"on-success"`

- `"on-failure"`

- `"on-abnormal"`

- `"on-watchdog"`

- `"on-abort"`

- `"always"`

restart_sec integer | Configures the time to sleep before restarting a service (as configured with restart-policy). Takes a value in seconds. Only with Podman 4.0.0 and above
separator string | Systemd unit name separator between the name/id of a container/pod and the prefix. If not set, use the default defined by podman, `-`. Refer to podman-generate-systemd(1) man page for more information.
start_timeout integer | Override the default start timeout for the container with the given value in seconds. Only with Podman 4.0.0 and above
stop_timeout integer | Override the default stop timeout for the container with the given value in seconds.

use_names

boolean

Use name of the containers for the start, stop, and description in the unit file.

Choices:

- `false`

- `true` ← (default)

wants

list / elements=string

Add the systemd unit wants (`Wants=`) option, that this service is (weak) dependent on.

This option may be specified more than once.

This option does not influence the order in which services are started or stopped.

User-defined dependencies will be appended to the generated unit file

But any existing options such as needed or defined by default (e.g. `online.target`) will not be removed or overridden.

Only with Podman 4.0.0 and above

## Notes

Note

- If you indicate a pod, the systemd units for it and all its containers will be generated

- Create all your pods, containers and their dependencies before generating the systemd files

- If a container or pod is already started before you do a `systemctl daemon-reload`, systemd will not see the container or pod as started

- Stop your container or pod before you do a `systemctl daemon-reload`, then you can start them with `systemctl start my_container.service`

## Examples

    # Example of creating a container and systemd unit file.
    # When using podman_generate_systemd with new:true then
    # the container needs rm:true for idempotence.
    - name: Create postgres container
      containers.podman.podman_container:
        name: postgres
        image: docker.io/library/postgres:latest
        rm: true
        state: created

    - name: Generate systemd unit file for postgres container
      containers.podman.podman_generate_systemd:
        name: postgres
        new: true
        no_header: true
        dest: /etc/systemd/system

    - name: Ensure postgres container is started and enabled
      ansible.builtin.systemd:
        name: container-postgres
        daemon_reload: true
        state: started
        enabled: true

    # Example of creating a container and integrate it into systemd
    - name: A postgres container must exist, stopped
      containers.podman.podman_container:
        name: postgres_local
        image: docker.io/library/postgres:latest
        state: stopped

    - name: Systemd unit files for postgres container must exist
      containers.podman.podman_generate_systemd:
        name: postgres_local
        dest: ~/.config/systemd/user/

    - name: Postgres container must be started and enabled on systemd
      ansible.builtin.systemd:
        name: container-postgres_local
        scope: user
        daemon_reload: true
        state: started
        enabled: true

    # Generate the unit files, but store them on an Ansible variable
    # instead of writing them on target host
    - name: Systemd unit files for postgres container must be generated
      containers.podman.podman_generate_systemd:
        name: postgres_local
      register: postgres_local_systemd_unit

    # Generate the unit files with environment variables sets
    - name: Systemd unit files for postgres container must be generated
      containers.podman.podman_generate_systemd:
        name: postgres_local
        env:
          POSTGRES_USER: my_app
          POSTGRES_PASSWORD: example
      register: postgres_local_systemd_unit

## Return Values

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

Key | Description
--- | ---
podman_command string | A copy of the podman command used to generate the systemd unit(s) Returned: always Sample: `"podman generate systemd my_webapp"`
systemd_units dictionary | A copy of the generated systemd .service unit(s) Returned: always Sample: `{"container-postgres_local": " #Content of the systemd .servec unit for postgres_local container", "pod-my_webapp": " #Content of the systemd .servec unit for my_webapp pod"}`

### Authors

- Sébastien Gendre (@CyberFox001)

### Collection links

- Issue Tracker
- Repository (Sources)