3 files changed, 82 insertions, 6 deletions
diff --git a/docs/podman-create.1.md b/docs/podman-create.1.md
index 46fa4fcd4..35602f97b 100644
--- a/docs/podman-create.1.md
+++ b/docs/podman-create.1.md
@@ -710,12 +710,18 @@ Network Namespace - current sysctls allowed:
 
 Note: if you use the --network=host option these sysctls will not be allowed.
 
-**--systemd**=*true|false*
+**--systemd**=*true|false|always*
 
 Run container in systemd mode. The default is *true*.
 
-If the command you running inside of the container is systemd or init, podman
-will setup tmpfs mount points in the following directories:
+The value *always* enforces the systemd mode is enforced without
+looking at the executable name.  Otherwise, if set to true and the
+command you are running inside the container is systemd or
+/usr/sbin/init.
+
+If the command you are running inside of the container is systemd or
+/usr/sbin/init, Podman will setup tmpfs mount points in the following
+directories:
 
 /run, /run/lock, /tmp, /sys/fs/cgroup/systemd, /var/lib/journal
 
diff --git a/docs/podman-derivative-api b/docs/podman-derivative-api
new file mode 100644
index 000000000..1b6153df5
--- /dev/null
+++ b/docs/podman-derivative-api
@@ -0,0 +1,64 @@
+.TH How to use libpod for custom/derivative projects
+.PP
+libpod today is a Golang library and a CLI.  The choice of interface you make has advantages and disadvantages.
+
+.SH Running as a subprocess
+.PP
+Advantages:
+
+.RS
+.IP \(bu 2
+Many commands output JSON
+.IP \(bu 2
+Works with languages other than Golang
+.IP \(bu 2
+Easy to get started
+
+.RE
+
+.PP
+Disadvantages:
+
+.RS
+.IP \(bu 2
+Error handling is harder
+.IP \(bu 2
+May be slower
+.IP \(bu 2
+Can't hook into or control low\-level things like how images are pulled
+
+.RE
+
+.SH Vendoring into a Go project
+.PP
+Advantages:
+
+.RS
+.IP \(bu 2
+Significant power and control
+
+.RE
+
+.PP
+Disadvantages:
+
+.RS
+.IP \(bu 2
+You are now on the hook for container runtime security updates (partially, \fB\fCrunc\fR/\fB\fCcrun\fR are separate)
+.IP \(bu 2
+Binary size
+.IP \(bu 2
+Potential skew between multiple libpod versions operating on the same storage can cause problems
+
+.RE
+
+.SH Varlink
+.PP
+Some code exists for this; splits the difference.  Future uncertain.
+
+.SH Making the choice
+.PP
+A good question to ask first is: Do you want users to be able to use \fB\fCpodman\fR to manipulate the containers created by your project?
+If so, that makes it more likely that you want to run \fB\fCpodman\fR as a subprocess.  If you want a separate image store and a fundamentally
+different experience; if what you're doing with containers is quite different from those created by the \fB\fCpodman\fR CLI,
+that may drive you towards vendoring.
diff --git a/docs/podman-run.1.md b/docs/podman-run.1.md
index dfc634288..e255119d7 100644
--- a/docs/podman-run.1.md
+++ b/docs/podman-run.1.md
@@ -747,12 +747,18 @@ Network Namespace - current sysctls allowed:
 
 Note: if you use the `--network=host` option these sysctls will not be allowed.
 
-**--systemd**=*true|false*
+**--systemd**=*true|false|always*
 
 Run container in systemd mode. The default is *true*.
 
-If the command you are running inside of the container is systemd or init, Podman
-will setup tmpfs mount points in the following directories:
+The value *always* enforces the systemd mode is enforced without
+looking at the executable name.  Otherwise, if set to true and the
+command you are running inside the container is systemd or
+/usr/sbin/init.
+
+If the command you are running inside of the container is systemd or
+/usr/sbin/init, Podman will setup tmpfs mount points in the following
+directories:
 
 /run, /run/lock, /tmp, /sys/fs/cgroup/systemd, /var/lib/journal