13 files changed, 398 insertions, 3 deletions
diff --git a/docs/source/markdown/podman-build.1.md b/docs/source/markdown/podman-build.1.md
index 24093d414..8fcfe555e 100644
--- a/docs/source/markdown/podman-build.1.md
+++ b/docs/source/markdown/podman-build.1.md
@@ -650,6 +650,10 @@ If --userns-gid-map-group is specified, but --userns-uid-map-user is not
 specified, `podman` will assume that the specified group name is also a
 suitable user name to use as the default setting for this option.
 
+**NOTE:** When this option is specified by a rootless user, the specified
+mappings are relative to the rootless usernamespace in the container, rather
+than being relative to the host as it would be when run rootful.
+
 #### **--userns-gid-map-group**=*group*
 
 Specifies that a GID mapping which should be used to set ownership, at the
@@ -661,6 +665,10 @@ If --userns-uid-map-user is specified, but --userns-gid-map-group is not
 specified, `podman` will assume that the specified user name is also a
 suitable group name to use as the default setting for this option.
 
+**NOTE:** When this option is specified by a rootless user, the specified
+mappings are relative to the rootless usernamespace in the container, rather
+than being relative to the host as it would be when run rootful.
+
 #### **--uts**=*how*
 
 Sets the configuration for UTS namespaces when the handling `RUN` instructions.
diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md
index d6b90e17a..5c53f8601 100644
--- a/docs/source/markdown/podman-create.1.md
+++ b/docs/source/markdown/podman-create.1.md
@@ -833,6 +833,11 @@ A secret is a blob of sensitive data which a container needs at runtime but
 should not be stored in the image or in source control, such as usernames and passwords,
 TLS certificates and keys, SSH keys or other important generic strings or binary content (up to 500 kb in size).
 
+Secrets are copied and mounted into the container when a container is created. If a secret is deleted using
+`podman secret rm`, the container will still have access to the secret. If a secret is deleted and
+another secret is created with the same name, the secret inside the container will not change; the old
+secret value will still remain.
+
 Secrets are managed using the `podman secret` command.
 
 #### **--security-opt**=*option*
diff --git a/docs/source/markdown/podman-generate-kube.1.md b/docs/source/markdown/podman-generate-kube.1.md
index 019bae539..0e5a31ae6 100644
--- a/docs/source/markdown/podman-generate-kube.1.md
+++ b/docs/source/markdown/podman-generate-kube.1.md
@@ -6,10 +6,14 @@ podman-generate-kube - Generate Kubernetes YAML based on a pod or container
 **podman generate kube** [*options*] *container...* | *pod*
 
 ## DESCRIPTION
-**podman generate kube** will generate Kubernetes Pod YAML (v1 specification) from Podman one or more containers or a single pod. Whether
+**podman generate kube** will generate Kubernetes Pod YAML (v1 specification) from Podman from one or more containers or a single pod. Whether
 the input is for containers or a pod, Podman will always generate the specification as a Pod. The input may be in the form
 of a pod or one or more container names or IDs.
 
+Volumes appear in the generated YAML according to two different volume types. Bind-mounted volumes become *hostPath* volume types and named volumes become *persistentVolumeClaim* volume types. Generated *hostPath* volume types will be one of three subtypes depending on the state of the host path: *DirectoryOrCreate* when no file or directory exists at the host, *Directory* when host path is a directory, or *File* when host path is a file. The value for *claimName* for a *persistentVolumeClaim* is the name of the named volume registered in Podman.
+
+Potential name conflicts between volumes are avoided by using a standard naming scheme for each volume type. The *hostPath* volume types are named according to the path on the host machine, replacing forward slashes with hyphens less any leading and trailing forward slashes. The special case of the filesystem root, `/`, translates to the name `root`. Additionally, the name is suffixed with `-host` to avoid naming conflicts with *persistentVolumeClaim* volumes. Each *persistentVolumeClaim* volume type uses the name of its associated named volume suffixed with `-pvc`.
+
 Note that the generated Kubernetes YAML file can be used to re-run the deployment via podman-play-kube(1).
 
 ## OPTIONS
@@ -25,7 +29,7 @@ random port is assigned by Podman in the specification.
 
 ## EXAMPLES
 
-Create Kubernetes Pod YAML for a container called `some-mariadb` .
+Create Kubernetes Pod YAML for a container called `some-mariadb`.
 ```
 $ sudo podman generate kube some-mariadb
 # Generation of Kubernetes YAML is still under development!
@@ -81,6 +85,113 @@ spec:
 status: {}
 ```
 
+Create Kubernetes Pod YAML for a container with the directory `/home/user/my-data` on the host bind-mounted in the container to `/volume`.
+```
+$ podman generate kube my-container-with-bind-mounted-data
+# Generation of Kubernetes YAML is still under development!
+#
+# Save the output of this file and use kubectl create -f to import
+# it into Kubernetes.
+#
+# Created with podman-3.1.0-dev
+apiVersion: v1
+kind: Pod
+metadata:
+  creationTimestamp: "2021-03-18T16:26:08Z"
+  labels:
+    app: my-container-with-bind-mounted-data
+  name: my-container-with-bind-mounted-data
+spec:
+  containers:
+  - command:
+    - /bin/sh
+    env:
+    - name: PATH
+      value: /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+    - name: TERM
+      value: xterm
+    - name: container
+      value: podman
+    image: docker.io/library/alpine:latest
+    name: test-bind-mount
+    resources: {}
+    securityContext:
+      allowPrivilegeEscalation: true
+      capabilities:
+        drop:
+        - CAP_MKNOD
+        - CAP_NET_RAW
+        - CAP_AUDIT_WRITE
+      privileged: false
+      readOnlyRootFilesystem: false
+      seLinuxOptions: {}
+    volumeMounts:
+    - mountPath: /volume
+      name: home-user-my-data-host
+    workingDir: /
+  dnsConfig: {}
+  restartPolicy: Never
+  volumes:
+  - hostPath:
+      path: /home/user/my-data
+      type: Directory
+    name: home-user-my-data-host
+status: {}
+```
+
+Create Kubernetes Pod YAML for a container with the named volume `priceless-data` mounted in the container at `/volume`.
+```
+$ podman generate kube my-container-using-priceless-data
+# Generation of Kubernetes YAML is still under development!
+#
+# Save the output of this file and use kubectl create -f to import
+# it into Kubernetes.
+#
+# Created with podman-3.1.0-dev
+apiVersion: v1
+kind: Pod
+metadata:
+  creationTimestamp: "2021-03-18T16:26:08Z"
+  labels:
+    app: my-container-using-priceless-data
+  name: my-container-using-priceless-data
+spec:
+  containers:
+  - command:
+    - /bin/sh
+    env:
+    - name: PATH
+      value: /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+    - name: TERM
+      value: xterm
+    - name: container
+      value: podman
+    image: docker.io/library/alpine:latest
+    name: test-bind-mount
+    resources: {}
+    securityContext:
+      allowPrivilegeEscalation: true
+      capabilities:
+        drop:
+        - CAP_MKNOD
+        - CAP_NET_RAW
+        - CAP_AUDIT_WRITE
+      privileged: false
+      readOnlyRootFilesystem: false
+      seLinuxOptions: {}
+    volumeMounts:
+    - mountPath: /volume
+      name: priceless-data-pvc
+    workingDir: /
+  dnsConfig: {}
+  restartPolicy: Never
+  volumes:
+  - name: priceless-data-pvc
+    persistentVolumeClaim:
+      claimName: priceless-data
+status: {}
+```
+
 Create Kubernetes Pod YAML for a pod called `demoweb` and include a service.
 ```
 $ sudo podman generate kube -s demoweb
diff --git a/docs/source/markdown/podman-machine-init.1.md b/docs/source/markdown/podman-machine-init.1.md
new file mode 100644
index 000000000..5ff07de03
--- /dev/null
+++ b/docs/source/markdown/podman-machine-init.1.md
@@ -0,0 +1,53 @@
+% podman-machine-init(1)
+
+## NAME
+podman\-machine\-init - Initialize a new virtual machine
+
+## SYNOPSIS
+**podman machine init** [*options*] [*name*]
+
+## DESCRIPTION
+
+Initialize a new virtual machine for Podman.
+
+Podman on MacOS requires a virtual machine. This is because containers are Linux -
+containers do not run on any other OS because containers' core functionality are
+tied to the Linux kernel.
+
+**podman machine init** initializes a new Linux virtual machine where containers are run.
+
+## OPTIONS
+
+#### **--cpus**=*number*
+
+Number of CPUs.
+
+#### **--ignition-path**
+
+Fully qualified path of the ignition file
+
+#### **--image-path**
+
+Fully qualified path of the uncompressed image file
+
+#### **--memory**, **-m**=*number*
+
+Memory (in MB).
+
+#### **--help**
+
+Print usage statement.
+
+## EXAMPLES
+
+```
+$ podman machine init myvm
+$ podman machine init --device=/dev/xvdc:rw myvm
+$ podman machine init --memory=1024 myvm
+```
+
+## SEE ALSO
+podman-machine (1)
+
+## HISTORY
+March 2021, Originally compiled by Ashley Cui <acui@redhat.com>
diff --git a/docs/source/markdown/podman-machine-remove.1.md b/docs/source/markdown/podman-machine-remove.1.md
new file mode 100644
index 000000000..07763741d
--- /dev/null
+++ b/docs/source/markdown/podman-machine-remove.1.md
@@ -0,0 +1,65 @@
+% podman-machine-remove(1)
+
+## NAME
+podman\-machine\-remove - Remove a virtual machine
+
+## SYNOPSIS
+**podman machine remove** [*options*] *name*
+
+## DESCRIPTION
+
+Remove a virtual machine and its related files.  What is actually deleted
+depends on the virtual machine type.  For all virtual machines, the generated
+SSH keys and the podman system connection are deleted.  The ignition files
+generated for that VM are also removeed as is its image file on the filesystem.
+
+Users get a display of what will be deleted and are required to confirm unless the option `--force`
+is used.
+
+
+## OPTIONS
+
+#### **--help**
+
+Print usage statement.
+
+#### **--force**
+
+Delete without confirmation
+
+#### **--save-ignition**
+
+Do not delete the generated ignition file
+
+#### **--save-image**
+
+Do not delete the VM image
+
+#### **--save-keys**
+
+Do not delete the SSH keys for the VM.  The system connection is always
+deleted.
+
+## EXAMPLES
+
+Remove a VM named "test1"
+
+```
+$ podman machine remove test1
+
+The following files will be deleted:
+
+/home/user/.ssh/test1
+/home/user/.ssh/test1.pub
+/home/user/.config/containers/podman/machine/qemu/test1.ign
+/home/user/.local/share/containers/podman/machine/qemu/test1_fedora-coreos-33.20210315.1.0-qemu.x86_64.qcow2
+/home/user/.config/containers/podman/machine/qemu/test1.json
+
+Are you sure you want to continue? [y/N] y
+```
+
+## SEE ALSO
+podman-machine (1)
+
+## HISTORY
+March 2021, Originally compiled by Ashley Cui <acui@redhat.com>
diff --git a/docs/source/markdown/podman-machine-ssh.1.md b/docs/source/markdown/podman-machine-ssh.1.md
new file mode 100644
index 000000000..bcecd1010
--- /dev/null
+++ b/docs/source/markdown/podman-machine-ssh.1.md
@@ -0,0 +1,43 @@
+% podman-machine-ssh(1)
+
+## NAME
+podman\-machine\-ssh - SSH into a virtual machine
+
+## SYNOPSIS
+**podman machine ssh** [*options*] *name* [*command* [*arg* ...]]
+
+## DESCRIPTION
+
+SSH into a Podman-managed virtual machine.
+
+Podman on MacOS requires a virtual machine. This is because containers are Linux -
+containers do not run on any other OS because containers' core functionality are
+tied to the Linux kernel.
+
+## OPTIONS
+
+#### **--execute**, **-e**
+
+Execute the given command on the VM
+
+#### **--help**
+
+Print usage statement.
+
+## EXAMPLES
+
+To get an interactive session with a VM called `myvm`:
+```
+$ podman machine ssh myvm
+```
+
+To run a command on a VM called `myvm`:
+```
+$ podman machine ssh -e myvm -- rpm -q podman
+```
+
+## SEE ALSO
+podman-machine (1)
+
+## HISTORY
+March 2021, Originally compiled by Ashley Cui <acui@redhat.com>
diff --git a/docs/source/markdown/podman-machine-start.1.md b/docs/source/markdown/podman-machine-start.1.md
new file mode 100644
index 000000000..511296b11
--- /dev/null
+++ b/docs/source/markdown/podman-machine-start.1.md
@@ -0,0 +1,35 @@
+% podman-machine-start(1)
+
+## NAME
+podman\-machine\-start - Start a virtual machine
+
+## SYNOPSIS
+**podman machine start** *name*
+
+## DESCRIPTION
+
+Starts a virtual machine for Podman.
+
+Podman on MacOS requires a virtual machine. This is because containers are Linux -
+containers do not run on any other OS because containers' core functionality are
+tied to the Linux kernel.
+
+**podman machine start** starts a Linux virtual machine where containers are run.
+
+## OPTIONS
+
+#### **--help**
+
+Print usage statement.
+
+## EXAMPLES
+
+```
+$ podman machine start myvm
+```
+
+## SEE ALSO
+podman-machine (1)
+
+## HISTORY
+March 2021, Originally compiled by Ashley Cui <acui@redhat.com>
diff --git a/docs/source/markdown/podman-machine-stop.1.md b/docs/source/markdown/podman-machine-stop.1.md
new file mode 100644
index 000000000..62439cbb1
--- /dev/null
+++ b/docs/source/markdown/podman-machine-stop.1.md
@@ -0,0 +1,35 @@
+% podman-machine-stop(1)
+
+## NAME
+podman\-machine\-stop - Stop a virtual machine
+
+## SYNOPSIS
+**podman machine stop** *name*
+
+## DESCRIPTION
+
+Stops a virtual machine.
+
+Podman on MacOS requires a virtual machine. This is because containers are Linux -
+containers do not run on any other OS because containers' core functionality are
+tied to the Linux kernel.
+
+**podman machine stop** stops a Linux virtual machine where containers are run.
+
+## OPTIONS
+
+#### **--help**
+
+Print usage statement.
+
+## EXAMPLES
+
+```
+$ podman machine stop myvm
+```
+
+## SEE ALSO
+podman-machine (1)
+
+## HISTORY
+March 2021, Originally compiled by Ashley Cui <acui@redhat.com>
diff --git a/docs/source/markdown/podman-machine.1.md b/docs/source/markdown/podman-machine.1.md
new file mode 100644
index 000000000..0e3c1ca34
--- /dev/null
+++ b/docs/source/markdown/podman-machine.1.md
@@ -0,0 +1,26 @@
+% podman-machine(1)
+
+## NAME
+podman\-machine - Manage Podman's virtual machine
+
+## SYNOPSIS
+**podman machine** *subcommand*
+
+## DESCRIPTION
+`podman machine` is a set of subcommands that manage Podman's virtual machine on MacOS.
+
+## SUBCOMMANDS
+
+| Command | Man Page                                                | Description                       |
+| ------- | ------------------------------------------------------- | --------------------------------- |
+| init    | [podman-machine-init(1)](podman-machine-init.1.md)      | Initialize a new virtual machine  |
+| remove  | [podman-machine-remove(1)](podman-machine-remove.1.md)  | Remove a virtual machine          |
+| ssh     | [podman-machine-ssh(1)](podman-machine-ssh.1.md)        | SSH into a virtual machine        |
+| start   | [podman-machine-start(1)](podman-machine-start.1.md)    | Start a virtual machine           |
+| stop    | [podman-machine-stop(1)](podman-machine-stop.1.md)      | Stop a virtual machine            |
+
+## SEE ALSO
+podman(1)
+
+## HISTORY
+March 2021, Originally compiled by Ashley Cui <acui@redhat.com>
diff --git a/docs/source/markdown/podman-play-kube.1.md b/docs/source/markdown/podman-play-kube.1.md
index 0a34a622f..1be597b94 100644
--- a/docs/source/markdown/podman-play-kube.1.md
+++ b/docs/source/markdown/podman-play-kube.1.md
@@ -11,7 +11,9 @@ podman-play-kube - Create pods and containers based on Kubernetes YAML
 
 Ideally the input file would be one created by Podman (see podman-generate-kube(1)).  This would guarantee a smooth import and expected results.
 
-Note: HostPath volume types created by play kube will be given an SELinux private label (Z)
+Only two volume types are supported by play kube, the *hostPath* and *persistentVolumeClaim* volume types. For the *hostPath* volume type, only the  *default (empty)*, *DirectoryOrCreate*, *Directory*, *FileOrCreate*, *File*, and *Socket* subtypes are supported. The *CharDevice* and *BlockDevice* subtypes are not supported. Podman interprets the value of *hostPath* *path* as a file path when it contains at least one forward slash, otherwise Podman treats the value as the name of a named volume. When using a *persistentVolumeClaim*, the value for *claimName* is the name for the Podman named volume.
+
+Note: *hostPath* volume types created by play kube will be given an SELinux private label (Z)
 
 Note: If the `:latest` tag is used, Podman will attempt to pull the image from a registry. If the image was built locally with Podman or Buildah, it will have `localhost` as the domain, in that case, Podman will use the image from the local store even if it has the `:latest` tag.
 
diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md
index 78b036cee..f61344099 100644
--- a/docs/source/markdown/podman-run.1.md
+++ b/docs/source/markdown/podman-run.1.md
@@ -885,6 +885,11 @@ A secret is a blob of sensitive data which a container needs at runtime but
 should not be stored in the image or in source control, such as usernames and passwords,
 TLS certificates and keys, SSH keys or other important generic strings or binary content (up to 500 kb in size).
 
+Secrets are copied and mounted into the container when a container is created. If a secret is deleted using
+`podman secret rm`, the container will still have access to the secret. If a secret is deleted and
+another secret is created with the same name, the secret inside the container will not change; the old
+secret value will still remain.
+
 Secrets are managed using the `podman secret` command
 
 #### **--security-opt**=*option*
diff --git a/docs/source/markdown/podman-secret-rm.1.md b/docs/source/markdown/podman-secret-rm.1.md
index 5169626dc..c6f5079ba 100644
--- a/docs/source/markdown/podman-secret-rm.1.md
+++ b/docs/source/markdown/podman-secret-rm.1.md
@@ -10,6 +10,12 @@ podman\-secret\-rm - Remove one or more secrets
 
 Removes one or more secrets.
 
+`podman secret rm` is safe to use on secrets that are in use by a container.
+The created container will still have access to the secret data because secrets are
+copied and mounted into the container when a container is created. If a secret is deleted and
+another secret is created with the same name, the secret inside the container will not change;
+the old secret value will still remain.
+
 ## OPTIONS
 
 #### **--all**, **-a**
diff --git a/docs/source/markdown/podman.1.md b/docs/source/markdown/podman.1.md
index 141d231f3..7bf7aa210 100644
--- a/docs/source/markdown/podman.1.md
+++ b/docs/source/markdown/podman.1.md
@@ -237,6 +237,7 @@ the exit codes follow the `chroot` standard, see below:
 | [podman-login(1)](podman-login.1.md)             | Login to a container registry.                                              |
 | [podman-logout(1)](podman-logout.1.md)           | Logout of a container registry.                                             |
 | [podman-logs(1)](podman-logs.1.md)               | Display the logs of one or more containers.                                 |
+| [podman-machine(1)](podman-machine.1.md)         | Manage Podman's virtual machine                                             |
 | [podman-manifest(1)](podman-manifest.1.md)       | Create and manipulate manifest lists and image indexes.                     |
 | [podman-mount(1)](podman-mount.1.md)             | Mount a working container's root filesystem.                                |
 | [podman-network(1)](podman-network.1.md)         | Manage Podman CNI networks.                                                 |