From 9f84d2ee27e4bb5376443b8854996f07eed08052 Mon Sep 17 00:00:00 2001 From: TomSweeneyRedHat Date: Thu, 19 Sep 2019 18:28:27 -0400 Subject: Move rootless and Mac to Tutorials page As the title says. Signed-off-by: TomSweeneyRedHat --- README.md | 4 +- docs/tutorials/README.md | 8 +++- docs/tutorials/mac_client.md | 99 +++++++++++++++++++++++++++++++++++++++++ docs/tutorials/remote_client.md | 77 ++++++++++++++++++++++++++++++++ mac_client.md | 99 ----------------------------------------- remote_client.md | 77 -------------------------------- 6 files changed, 184 insertions(+), 180 deletions(-) create mode 100644 docs/tutorials/mac_client.md create mode 100644 docs/tutorials/remote_client.md delete mode 100644 mac_client.md delete mode 100644 remote_client.md diff --git a/README.md b/README.md index f04dd75d5..4cdccd3a9 100644 --- a/README.md +++ b/README.md @@ -102,10 +102,10 @@ includes tables showing Docker commands and their Podman equivalent commands. **[Tutorials](docs/tutorials)** Tutorials on using Podman. -**[Remote Client](remote_client.md)** +**[Remote Client](https://github.com/containers/libpod/blob/master/docs/tutorials/remote_client.md)** A brief how-to on using the Podman remote-client. -**[Basic Setup and Use of Podman in a Rootless environment](https://github.com/containers/libpod/blob/master/docs/tutorials/rootless_tutorial.md) +**[Basic Setup and Use of Podman in a Rootless environment](https://github.com/containers/libpod/blob/master/docs/tutorials/rootless_tutorial.md)** A tutorial showing the setup and configuration necessary to run Rootless Podman. **[Release Notes](RELEASE_NOTES.md)** 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 +``` diff --git a/mac_client.md b/mac_client.md deleted file mode 100644 index bf08e8cc1..000000000 --- a/mac_client.md +++ /dev/null @@ -1,99 +0,0 @@ -# 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/remote_client.md b/remote_client.md deleted file mode 100644 index be5c918c8..000000000 --- a/remote_client.md +++ /dev/null @@ -1,77 +0,0 @@ -# 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](install.md) and follow the -section [Building from scratch](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 -``` -- cgit v1.2.3-54-g00ecf