github.com/containers/libpod@v1.9.4-0.20220419124438-4284fd425507/docs/tutorials/remote_client.md (about)

     1  # Podman remote-client tutorial
     2  
     3  ## What is the remote-client
     4  
     5  First and foremost, the remote-client is under heavy development.  We are adding new
     6  commands and functions frequently.  We also are working on a rootless implementation that
     7  does not require privileged users.
     8  
     9  The purpose of the Podman remote-client is to allow users to interact with a Podman "backend"
    10  while on a separate client.  The command line interface of the remote client is exactly the
    11  same as the regular Podman commands with the exception of some flags being removed as they
    12  do not apply to the remote-client.
    13  
    14  ## What you need
    15  To use the remote-client, you will need a binary for your client and a Podman "backend"; hereafter
    16  referred to as the Podman node.  In this context, a Podman node is a Linux system with Podman
    17  installed on it and the varlink service activated.  You will also need to be able to ssh into this
    18  system as a user with privileges to the varlink socket (more on this later).
    19  
    20  ## Building the remote client
    21  At this time, the Podman remote-client is not being packaged for any distribution.  It must be built from
    22  source.  To set up your build environment, see [Installation notes](https://github.com/containers/libpod/blob/master/install.md) and follow the
    23  section [Building from scratch](https://github.com/containers/libpod/blob/master/install.md#building-from-scratch).  Once you can successfully
    24  build the regular Podman binary, you can now build the remote-client.
    25  ```
    26  $ make podman-remote
    27  ```
    28  Like building the regular Podman, the resulting binary will be in the *bin* directory.  This is the binary
    29  you will run on the remote node later in the instructions.
    30  
    31  ## Setting up the remote and Podman nodes
    32  
    33  To use the remote-client, you must perform some setup on both the remote and Podman nodes. In this case,
    34  the remote node refers to where the remote-client is being run; and the Podman node refers to where
    35  Podman and its storage reside.
    36  
    37  
    38  ### Podman node setup
    39  
    40  Varlink bridge support is provided by the varlink cli command and installed using:
    41  ```
    42  $ sudo dnf install varlink-cli
    43  ```
    44  
    45  The Podman node must have Podman (not the remote-client) installed as normal. If your system uses systemd,
    46  then simply start the Podman varlink socket.
    47  ```
    48  $ sudo systemctl start io.podman.socket
    49  ```
    50  
    51  If your system cannot use systemd, then you can manually establish the varlink socket with the Podman
    52  command:
    53  ```
    54  $ sudo podman --log-level debug varlink --timeout 0  unix://run/podman/io.podman
    55  ```
    56  
    57  ### Required permissions
    58  For now, the remote-client requires that you be able to run a privileged Podman and have privileged ssh
    59  access to the remote system.  This limitation is being worked on.
    60  
    61  ### Remote node setup
    62  
    63  #### Initiate an ssh session to the Podman node
    64  To use the remote client, an ssh connection to the Podman server must be established.
    65  
    66  Using the varlink bridge, an ssh tunnel must be initiated to connect to the server. Podman must then be informed of the location of the sshd server on the targeted server
    67  
    68  ```
    69  $ export PODMAN_VARLINK_BRIDGE=$'ssh -T -p22 root@remotehost -- "varlink -A \'podman varlink \$VARLINK_ADDRESS\' bridge"'
    70  $ bin/podman-remote images
    71  REPOSITORY                     TAG      IMAGE ID       CREATED         SIZE
    72  docker.io/library/ubuntu       latest   47b19964fb50   2 weeks ago     90.7 MB
    73  docker.io/library/alpine       latest   caf27325b298   3 weeks ago     5.8 MB
    74  quay.io/cevich/gcloud_centos   latest   641dad61989a   5 weeks ago     489 MB
    75  k8s.gcr.io/pause               3.1      da86e6ba6ca1   14 months ago   747 kB
    76  ```
    77  
    78  The PODMAN_VARLINK_BRIDGE variable may be added to your log in settings. It does not change per connection.
    79  
    80  If coming from a Windows machine, the PODMAN_VARLINK_BRIDGE is formatted as:
    81  ```
    82  set PODMAN_VARLINK_BRIDGE=C:\Windows\System32\OpenSSH\ssh.exe -T -p22 root@remotehost -- varlink -A "podman varlink $VARLINK_ADDRESS" bridge
    83  ```
    84  
    85  The arguments before the `--` are presented to ssh while the arguments after are for the varlink cli. The varlink arguments should be copied verbatim.
    86   - `-p` is the port on the remote host for the ssh tunnel.  `22` is the default.
    87   - `root` is the currently supported user, while `remotehost` is the name or IP address of the host providing the Podman service.
    88   - `-i` may be added to select an identity file.