# containers.podman.podman_system_connection module – Manage podman system connections

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_system_connection`.

New in containers.podman 1.18.0

## Synopsis

- Manage podman system connections with podman system connection command.

- Add, remove, rename and set default connections to Podman services.

## Requirements

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

- podman

## Parameters

Parameter | Comments
--- | ---

default

boolean

Make this connection the default for this user

Choices:

- `false`

- `true`

destination string | Destination for the connection. Required when state=present. Can be in the format `[user@]hostname[:port]`, `ssh://[user@]hostname[:port]`, `unix://path`, `tcp://hostname:port`
executable string | Path to `podman` executable if it is not in the `$PATH` on the machine running `podman` Default: `"podman"`
identity string | Path to SSH identity file
name string / required | Name of the connection
new_name string | New name for the connection when renaming (used with state=present)
port integer | SSH port (default is 22)
socket_path string | Path to the Podman service unix domain socket on the ssh destination host

state

string

State of the connection

Choices:

- `"present"` ← (default)

- `"absent"`

## Examples

    - name: Add a basic SSH connection
      containers.podman.podman_system_connection:
        name: production
        destination: root@server.example.com
        state: present

    - name: Add SSH connection with custom port and identity
      containers.podman.podman_system_connection:
        name: staging
        destination: user@staging.example.com
        port: 2222
        identity: ~/.ssh/staging_rsa
        state: present

    - name: Add connection and set as default
      containers.podman.podman_system_connection:
        name: development
        destination: dev@dev.example.com
        default: true
        state: present

    - name: Add unix socket connection
      containers.podman.podman_system_connection:
        name: local
        destination: unix:///run/podman/podman.sock
        state: present

    - name: Add TCP connection
      containers.podman.podman_system_connection:
        name: remote_tcp
        destination: tcp://remote.example.com:8080
        state: present

    - name: Rename a connection
      containers.podman.podman_system_connection:
        name: old_name
        new_name: new_name
        state: present

    - name: Remove a connection
      containers.podman.podman_system_connection:
        name: old_connection
        state: absent

## Return Values

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

Key | Description
--- | ---
actions list / elements=string | Actions performed on the connection Returned: always Sample: `["Connection 'production' added", "Connection 'production' set as default"]`
connection dictionary | Connection information in podman JSON format Returned: always Sample: `{"Default": true, "Name": "production", "ReadWrite": true, "URI": "ssh://root@server.example.com:22/run/user/0/podman/podman.sock"}`

### Authors

- Sagi Shnaidman (@sshnaidm)

### Collection links

- Issue Tracker
- Repository (Sources)