opensource/podman
1
0
Fork 0
mirror of https://github.com/containers/podman.git synced 2025-09-19 21:50:07 +08:00
Code Issues Packages Projects Releases Wiki Activity

Move rootless and Mac to Tutorials page

Browse Source 
As the title says.

Signed-off-by: TomSweeneyRedHat <tsweeney@redhat.com>
This commit is contained in:
TomSweeneyRedHat
2019-09-19 18:28:27 -04:00
parent c38844f5a9
commit 9f84d2ee27
4 changed files with 10 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/tutorials/README.md
View File

@ -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
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.

99
docs/tutorials/mac_client.md Normal file
View File

@ -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
```

77
docs/tutorials/remote_client.md Normal file
View File

@ -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
```