Merge pull request #4064 from TomSweeneyRedHat/dev/tsweeney/tutfix

Move rootless and Mac to Tutorials page

3 files changed, 182 insertions, 2 deletions

diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md
index 5dc01f794..c340d683f 100644
--- a/docs/tutorials/README.md
+++ b/docs/tutorials/README.md
@@ -12,6 +12,10 @@ Learn how to setup Podman and perform some basic commands with the utility.
 
 The steps required to setup rootless Podman are enumerated.
 
-**[Setup on OS X](https://github.com/containers/libpod/blob/master/mac_client.md)**
+**[Setup on OS X](https://github.com/containers/libpod/blob/master/doc/tutorials/mac_client.md)**
 
-Special setup for running the Podman remote client on a Mac and connecting to Podman running on a Linux VM are documented
\ No newline at end of file
+Special setup for running the Podman remote client on a Mac and connecting to Podman running on a Linux VM are documented
+
+**[Remote Client](https://github.com/containers/libpod/blob/master/doc/tutorials/remote_client.md)**
+
+A brief how-to on using the Podman remote-client.
diff --git a/docs/tutorials/mac_client.md b/docs/tutorials/mac_client.md
new file mode 100644
index 000000000..bf08e8cc1
--- /dev/null
+++ b/docs/tutorials/mac_client.md
@@ -0,0 +1,99 @@
+# Podman Mac Client tutorial
+
+## What is the Podman Mac Client
+
+First and foremost, the Mac Client is under heavy development. We are working on getting the
+Mac client to be packaged and run for a native-like experience. This is the setup tutorial
+for the Mac client at its current stage of development and packaging.
+
+The purpose of the Mac client for Podman is to allow users to run Podman on a Mac. Since Podman is a Linux
+container engine, The Mac client is actually a version of the [Podman-remote client](remote_client.md),
+edited to that the client side works on a Mac machine, and connects to a Podman "backend" on a Linux
+machine, virtual or physical. The goal is to have a native-like experience when working with the Mac
+client, so the command line interface of the remote client is exactly the same as the regular Podman
+commands with the exception of some flags and commands that do not apply to the Mac client.
+
+## What you need
+
+To use the Mac client, you will need a binary built for MacOS and a Podman "backend" on a Linux machine;
+hereafter referred to as the Podman node. In this context, a Podman node is a Linux system with Podman
+installed on it and the varlink service activated.  You will also need to be able to ssh into this
+system as a user with privileges to the varlink socket (more on this later).
+
+For best results, use the most recent version of MacOS
+
+## Getting the Mac client
+The Mac client is available through [Homebrew](https://brew.sh/).
+```
+$ brew cask install podman
+```
+
+## Setting up the client and Podman node connection
+
+To use the Mac client, you must perform some setup on both the Mac and Podman nodes. In this case,
+the Mac node refers to the Mac on which Podman is being run; and the Podman node refers to where
+Podman and its storage reside.
+
+### Connection settings
+Your Linux box must have ssh enabled, and you must copy your Mac's public key from `~/.sconf sh/id.pub` to
+`/root/.ssh/authorized_keys` on your Linux box using `ssh-copy-id` This allows for the use of SSH keys
+for remote access.
+
+You may need to edit your `/etc/ssh/sshd_config` in your Linux machine as follows:
+```
+PermitRootLogin yes
+```
+
+Use of SSH keys are strongly encouraged to ensure a secure login. However, if you wish to avoid ‘logging in’ every
+time you run a Podman command, you may edit your `/etc/ssh/sshd_config` on your Linux machine as follows:
+```
+PasswordAuthentication no
+PermitRootLogin without-password
+```
+
+### Podman node setup
+The Podman node must be running a Linux distribution that supports Podman and must have Podman (not the Mac
+client) installed. You must also have root access to the node. Check if your system uses systemd:
+```
+$cat /proc/1/comm
+systemd
+```
+If it does, then simply start the Podman varlink socket:
+```
+$ sudo systemctl start io.podman.socket
+$ sudo systemctl enable io.podman.socket
+```
+
+If your system cannot use systemd, then you can manually establish the varlink socket with the Podman
+command:
+```
+$ sudo podman --log-level debug varlink --timeout 0  unix://run/podman/io.podman
+```
+
+### Required permissions
+For now, the Mac client requires that you be able to run a privileged Podman and have privileged ssh
+access to the remote system.  This limitation is being worked on.
+
+#### Running the remote client
+There are three different ways to pass connection information into the client: flags, conf file, and
+environment variables. All three require information on username and a remote host ip address. Most often,
+your username should be root and you can obtain your remote-host-ip using `ip addr`
+
+To connect using flags, you can use
+```
+$ podman --remote-host remote-host-ip --username root images
+REPOSITORY                 TAG               IMAGE ID       CREATED         SIZE
+quay.io/podman/stable      latest            9c1e323be87f   10 days ago     414 MB
+localhost/test             latest            4b8c27c343e1   4 weeks ago     253 MB
+k8s.gcr.io/pause           3.1               da86e6ba6ca1   20 months ago   747 kB
+```
+If the conf file is set up, you may simply use Podman as you would on the linux machine. Take a look at
+[podman-remote.conf.5.md](https://github.com/containers/libpod/blob/master/docs/podman-remote.conf.5.md) on how to use the conf file:
+
+```
+$ podman images
+REPOSITORY                 TAG               IMAGE ID       CREATED         SIZE
+quay.io/podman/stable      latest            9c1e323be87f   10 days ago     414 MB
+localhost/test             latest            4b8c27c343e1   4 weeks ago     253 MB
+k8s.gcr.io/pause           3.1               da86e6ba6ca1   20 months ago   747 kB
+```
diff --git a/docs/tutorials/remote_client.md b/docs/tutorials/remote_client.md
new file mode 100644
index 000000000..197ff3d26
--- /dev/null
+++ b/docs/tutorials/remote_client.md
@@ -0,0 +1,77 @@
+# Podman remote-client tutorial
+
+## What is the remote-client
+
+First and foremost, the remote-client is under heavy development.  We are adding new
+commands and functions frequently.  We also are working on a rootless implementation that
+does not require privileged users.
+
+The purpose of the Podman remote-client is to allow users to interact with a Podman "backend"
+while on a separate client.  The command line interface of the remote client is exactly the
+same as the regular Podman commands with the exception of some flags being removed as they
+do not apply to the remote-client.
+
+## What you need
+To use the remote-client, you will need a binary for your client and a Podman "backend"; hereafter
+referred to as the Podman node.  In this context, a Podman node is a Linux system with Podman
+installed on it and the varlink service activated.  You will also need to be able to ssh into this
+system as a user with privileges to the varlink socket (more on this later).
+
+## Building the remote client
+At this time, the remote-client is not being packaged for any distribution.  It must be built from
+source.  To set up your build environment, see [Installation notes](https://github.com/containers/libpod/blob/master/install.md) and follow the
+section [Building from scratch](https://github.com/containers/libpod/blob/master/install.md#building-from-scratch).  Once you can successfully
+build the regular Podman binary, you can now build the remote-client.
+```
+$ make podman-remote
+```
+Like building the regular Podman, the resulting binary will be in the *bin* directory.  This is the binary
+you will run on the remote node later in the instructions.
+
+## Setting up the remote and Podman nodes
+
+To use the remote-client, you must perform some setup on both the remote and Podman nodes. In this case,
+the remote node refers to where the remote-client is being run; and the Podman node refers to where
+Podman and its storage reside.
+
+### Podman node setup
+The Podman node must have Podman (not the remote-client) installed as normal. If your system uses systemd,
+then simply start the Podman varlink socket.
+```
+$ sudo systemctl start io.podman.socket
+```
+
+If your system cannot use systemd, then you can manually establish the varlink socket with the Podman
+command:
+```
+$ sudo podman --log-level debug varlink --timeout 0  unix://run/podman/io.podman
+```
+
+### Required permissions
+For now, the remote-client requires that you be able to run a privileged Podman and have privileged ssh
+access to the remote system.  This limitation is being worked on.
+
+### Remote node setup
+
+#### Initiate an ssh session to the Podman node
+To use the remote client, we must establish an ssh connection to the Podman server.  We will also use
+that session to bind the remote varlink socket locally.
+
+```
+$ ssh -L 127.0.0.1:1234:/run/podman/io.podman root@remotehost
+```
+Note here we are binding the Podman socket to a local TCP socket on port 1234.
+
+#### Running the remote client
+With the ssh session established, we can now run the remote client in a different terminal window. You
+must inform Podman where to look for the bound socket you created in the previous step using an
+environment variable.
+
+```
+$ PODMAN_VARLINK_ADDRESS="tcp:127.0.0.1:1234" bin/podman-remote images
+REPOSITORY                     TAG      IMAGE ID       CREATED         SIZE
+docker.io/library/ubuntu       latest   47b19964fb50   2 weeks ago     90.7 MB
+docker.io/library/alpine       latest   caf27325b298   3 weeks ago     5.8 MB
+quay.io/cevich/gcloud_centos   latest   641dad61989a   5 weeks ago     489 MB
+k8s.gcr.io/pause               3.1      da86e6ba6ca1   14 months ago   747 kB
+```