The other direction: fix or clean up elements documented in
man pages but which did/do not exist in actual podman:
* runlabel: add missing "-n" alias for --name
And, remove man page entries for nonexistent options:
* podman commit: --iidfile
* podman container runlabel: --rootfs, --storage
* podman create: --cpu-count
There are two problems I don't know how to deal with. Both
are related to main_local.go:rootCmd.PersistentFlags() :
1) podman-build.1.md documents --cni-config-dir and
--runtime options, but these are not actually options
under podman build; they are global options. The
documentation in this man page differs from that
under podman-build.
2) podman ps implements a binary --namespace option,
but this option does not (cannot?) appear in --help
because there's a global --namespace string option
and Cobra somehow gets confused about this.
Do we really intend for global options to be parsed on
the right-hand side of subcommands? This strikes me as
unintuitive and potentially confusing, although the
fact that it has taken me this long to discover it
suggests that it's not _that_ confusing.
Suggestions welcome. I can file issues for 1/2 above,
or simply teach my script to special-case ignore them.
Signed-off-by: Ed Santiago <santiago@redhat.com>
I wrote a script to cross-reference podman --help against
man pages. It found a bunch of inconsistencies fix them:
* options missing from man pages
* options misspelled or misformatted in man pages (usually
misplaced asterisks or missing dashes, but see --dns-opt)
* one spurious comma in the actual source file --help
This is a fix in which I iterate over 'podman CMD --help'
and check for presence in man pages. The other way around
(look for flags in man pages, check podman CMD --help)
is probably impossible: there are too many special cases
Signed-off-by: Ed Santiago <santiago@redhat.com>
Clarify in the man page that --syslog expexts an argument to prevent
users from believing it's a switch.
Signed-off-by: Valentin Rothberg <rothberg@redhat.com>
When enabling a systemd service we can specify which target will start
it by specifying it in the `[INSTALL]` section. In case of root, this
is commonly set to `multi-user.target` which is used to start other
essential system services such as the network manager, D-BUS and more.
However, the `multi-user.target` is not enough on all systems,
especially when running rootless and enabling user services. Multiple
users have reported issues that there isn't even an attempt to start the
service.
Setting the INSTALL target to `default.target` will fix the rootless
case. However, `default.target` may vary among systems. Fedora
Workstation, for instance, sets the `default.target` to the graphical
target (i.e., runlevel 5) while Fedora Server sets it to
`multi-user.target` which is on runlevel 2 and hence way earlier in the
startup sequence.
As INSTALL allows for specifying multiple INSTALL targets, we can set it
to `multi-user.target` to continue supporting existing workloads AND to
`default.target` which MAY redundantly attempt to start it at a later point;
effectively a NOP for the root case and essential for rootless.
Fixes: #5423
Signed-off-by: Valentin Rothberg <rothberg@redhat.com>
Some users have small /var/tmp directories and need to be able to specify a different location
for temporary files, which includes more space.
Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
The --rmi flag will delete the container image after its execution
unless that image is already been used by another container(s).
This is useful when one wants to execute a container once and remove
any resources attached to it.
Signed-off-by: Boaz Shuster <boaz.shuster.github@gmail.com>
This patch allows users to specify the list of capabilities required
to run their container image.
Setting a image/container label "io.containers.capabilities=setuid,setgid"
tells podman that the contained image should work fine with just these two
capabilties, instead of running with the default capabilities, podman will
launch the container with just these capabilties.
If the user or image specified capabilities that are not in the default set,
the container will print an error message and will continue to run with the
default capabilities.
Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
Also apply changes from commit 3fd9f0c028
to the other two commands that have the --device option.
Documents #4550
Signed-off-by: Stefan Becker <chemobejk@gmail.com>
Now support --no-healthcheck option to disable defined healthchecks in a container image. --health-cmd=none remains supported as well.
Fixes: #5299
Signed-off-by: Brent Baude <bbaude@redhat.com>
Looks like a bit of a misunderstanding from early on.
Docker implements --filter=since=IMAGE. Podman implements 'after'
instead of 'since'. Add an equivalent case statement to handle
both, keeping 'after' because we have no way of knowing if it
is used in the field.
Update documentation ... and fix what looks like a complete
misinterpretation of what the code actually does: the man page
claimed that these were time fields, but I don't see any
possible incantation in which a time value works or could
work. Updated docs to reflect IMAGE usage. Also changed
nonworking '==' to single '='.
Added tests. [UPDATE: skip with broken podman-remote]
Fixes: #5040
Signed-off-by: Ed Santiago <santiago@redhat.com>
Enables most of the network-related functionality from
`podman run` in `podman pod create`. Custom CNI networks can be
specified, host networking is supported, DNS options can be
configured.
Also enables host networking in `podman play kube`.
Fixes#2808Fixes#3837Fixes#4432Fixes#4718Fixes#4770
Signed-off-by: Matthew Heon <matthew.heon@pm.me>
fix#5146
Insted of using a registry as mandatory parameter, this path allows podman to use the first registry from registries.conf.
Signed-off-by: Qi Wang <qiwan@redhat.com>
Following
Commit ba1d1304a6 ("make image reference for commit optional")
Updates usage text used by cobra and markdown document used to generate MAN page.
Fixes: #5145
Signed-off-by: Allan Jacquet-Cretides <allan.jacquet@gmail.com>
I saw some bad formatting when reading "man podman-run" and
proceeded to fix it. I have now opened a can of worms...
This commit tries to fix some of the formatting, wording and
other bugs I came across (unfortunately not all of them).
Can't list every fix that I made here, but in general:
- format lists as such (prepend items with "- ");
- format examples as such (enclose in ```...```);
- format literal values (option names, literal values) as **bold**;
- format man page references as **page**(1).
- format replacements (option values) and file names as _italic_;
- remove some duplicate info (such as what's the default value);
- move option value description to option syntax;
- end sentences with a period.
To test:
```console
$ make docs
$ man ./docs/build/man/podman-run.1 ### check terminal formatting
$ man -Tps ./docs/build/man/podman-run.1 > podman-run.ps
$ ps2pdf podman-run.ps ### optional
$ evince podman-run.pdf ### check printer formatting (or use ps viewr
```
NOTE
- there is much more to do here;
- I haven't checked any factual contents, this is about formatting
Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
fix#4876
Add `--device-cgroup-rule` to podman create and run. This enables to add device rules after the container has been created.
Signed-off-by: Qi Wang <qiwan@redhat.com>
This patch lets valid values of --format be compatible with docker. Replace CreatedTime with CreatedAt, Created with CreatedSince.
Keep CreatedTime and Created are valid as hidden options.
Signed-off-by: Qi Wang <qiwan@redhat.com>
When we filter, it should be out of all containers, not just
running ones, by default - this is necessary to ensure Docker
compatability.
Fixes#5050
Signed-off-by: Matthew Heon <mheon@redhat.com>
Apparently, a tilde is currently rendered as a single space, making
a mess of command examples that use it, so use $HOME instead.
https://github.com/mattermost/mattermost-server/issues/8228
Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
We no longer wish to hide the --arch-override from the cli on pulls. we now expose it. docs updated. tests already exist.
Fixes: #4849
Signed-off-by: Brent Baude <bbaude@redhat.com>
In both of "podman {container,image} exists" man pages, there
are superfluous uses of "sudo" in examples -- get rid of them.
Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
In addition to tweaking markdown, reword the explanation of
the "--volumes" option for clarity.
Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
Standardize markdown for options and commands, and add leading
dollar signs to emphasize commands being run.
Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
Since "man podman-version" seems to want to list everything printed
about the current version, add a reference to Remote API Version
for completeness.
Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
The conversion of markdown to man pages is causing "_" to cover entire lines.
This PR cleans this up and fixes some of the english.
Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
While fixing grammar and list formatting issues, standardize on
markdown as follows:
- commands are marked by '**'
- files are marked by backquotes
- list items are marked with leading '-'
Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
Move the seccomp profile from a manifest annotation to a config label.
This way, we can support it for Docker images as well and provide an
easy way to add that data via Dockerfiles.
Signed-off-by: Valentin Rothberg <rothberg@redhat.com>
Reword the man page to clarify that the '--size' option displays
the container size in addition to the normal output.
Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
add service endpoint for the new API. Also supports the varlink
implementation.
Signed-off-by: baude <bbaude@redhat.com>
Refactor to allow developer more control of API server
* Add api.NewServerWithSettings() to create an API server with custom
settings
* Add api.ListenUnix() to create a UDS net.Listener and setup UDS
Signed-off-by: Jhon Honce <jhonce@redhat.com>
Signed-off-by: baude <bbaude@redhat.com>
More service completion
Add podman service command that allows users to run either a RESTful or
varlink protocol API service.
Addition of docs and RESTful listening.
Signed-off-by: baude <bbaude@redhat.com>
Signed-off-by: Brent Baude <bbaude@redhat.com>
Add statement to the info section stating this is experimental only for now. Also add the podman logo to the right-hand navigation.
Signed-off-by: Brent Baude <bbaude@redhat.com>
The word `alias` is not very common when speaking about image names and
tags. So we just refer to image name as the overall identifier of an
image.
Signed-off-by: Sascha Grunert <sgrunert@suse.com>
it allows to disable cgroups creation only for the conmon process.
A new cgroup is created for the container payload.
Signed-off-by: Giuseppe Scrivano <gscrivan@redhat.com>
We have a lot of cludgy code trying to make --net and --network equivalent.
This will allow --net to still exists but will eliminate the help and confusion.
Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
This should help use keep the codebase more consistent, and avoid sevel
whitespace related issues, or bad file permissions.
pre-commit allows us to easily introduce other linters in follow-ups,
like bashate.
Note: pre-commit tool does *not* install any git-hooks. Making commits
will will call the tool unless you deliverately tell it to install the
hooks.
Signed-off-by: Sorin Sbarnea <ssbarnea@redhat.com>
the --force parameter should only be used for the CLI and should only
dictate whether to prompt the user for confirmation.
Fixes: #4844
Signed-off-by: baude <bbaude@redhat.com>
support a custom tag to add to each log for the container.
It is currently supported only by the journald backend.
Closes: https://github.com/containers/libpod/issues/3653
Signed-off-by: Giuseppe Scrivano <gscrivan@redhat.com>
Implement a policy for selecting a seccomp profile. In addition to the
default behaviour (default profile unless --security-opt seccomp is set)
add a second policy doing a lookup in the image annotation.
If the image has the "io.containers.seccomp.profile" set its value will be
interpreted as a seccomp profile. The policy can be selected via the
new --seccomp-policy CLI flag.
Once the containers.conf support is merged into libpod, we can add an
option there as well.
Note that this feature is marked as experimental and may change in the
future.
Signed-off-by: Valentin Rothberg <rothberg@redhat.com>
Add a --new flag to podman-generate-systemd to create a new container
via podman-run instead of starting an existing container.
Creating a new container presents the challenge to find a reverse
mapping from a container to the CLI flags it can be created with. We
are doing this via `(Container).Config.CreateCommand` field, which
includes a copy of the process' command from procFS at creating time.
This field may not be useful when the container was not created via the
Podman CLI (e.g., via a Python script). Hence, we do not guarantee the
correctness of the generated files.
Signed-off-by: Valentin Rothberg <rothberg@redhat.com>
Podman now supports untagging images via the `untag` sub-command for the
root and `image` commands. Testing and documentation has been added as
well.
Signed-off-by: Sascha Grunert <sgrunert@suse.com>
Two man pages had incorrect references to a nonexistent
policy.conf(5) or policy-conf(5) [dot vs dash]. Fix them.
Also checked for other broken references via:
$ for i in registries.conf storage.conf policy.json ; do grep -R $i.5 docs/source | grep -v containers-$i;done
(No further results found. That's not a guarantee that there
aren't other broken links though).
Signed-off-by: Ed Santiago <santiago@redhat.com>
Add flag --seccomp-profile-root in play kube to allow users to specify where to look for seccomp profiles
update tests
Signed-off-by: Peter Hunt <pehunt@redhat.com>
Currently the use of "*" in tables is causing go-md2man
to screw up the format of the man page.
This PR removes the "*" since it is not really necessary.
Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
During writing the tests I found it would be probably useful to have the
tag history part of the inspect data.
Signed-off-by: Sascha Grunert <sgrunert@suse.com>
c/psgo added a new `stime` descriptor. Mention that in the man page and
refer to podman-top(1) in podman-pod-top(1) to avoid redundancy.
Signed-off-by: Valentin Rothberg <rothberg@redhat.com>
If the user specifies .Server.* on a non podman-remote,
substitute .Client for .Server and return the value.
This is for compatability with Docker.
Since prior versions documented --format {{ .Version }}, we
have to continue to support that.
Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
This command will destroy all data created via podman.
It will remove containers, images, volumes, pods.
Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
We leverage the containers/storage image history tracking feature to
show the previously used image names when running:
`podman images --history`
Signed-off-by: Sascha Grunert <sgrunert@suse.com>
This path allows pod prune & pod rm to remove stopped containers in the pod before deleting the pod.
PrunePods and RemovePod should be able to remove containers without force removal of stopped pods.
Signed-off-by: Qi Wang <qiwan@redhat.com>
Add an --ignore flag to podman rm and stop. When specified, Podman will
ignore "no such {container,pod}" errors that occur when a specified
container/pod is not present in the store (anymore). The motivation
behind adding this flag is to write more robust systemd services using
Podman. A user might have manually decided to remove a container/pod
which would lead to a failure during the `ExecStop` directive of a
systemd service referencing that container/pod.
Signed-off-by: Valentin Rothberg <rothberg@redhat.com>
Add a --cidfile flag to podman rm/stop to pass a container ID via a
file. Podman run already provides the functionaly to store the ID
in a specified file which we now complete with rm/stop. This allows
for a better life-cycle management in systemd services. Note that
--cdifile can be specified multiple times to rm/stop.
Signed-off-by: Valentin Rothberg <rothberg@redhat.com>
Bump to Buildah v1.11.5. Most notably changes to the
podman build `--pull` functionality. `--pull=true` and `--pull=false` now
work as Docker does, `--pull-never` added to supply the functionality
of the old `--pull=false`.
Signed-off-by: TomSweeneyRedHat <tsweeney@redhat.com>
Add missing options.
Define the use of the TMPDIR environment variable for the storing of container images
when they are being pulled to the system.
Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
If user specifies --detach-keys="", this will disable the feature.
Adding define.DefaultDetachKeys to help screen to help identify detach keys.
Updated man pages with additonal information.
Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
change the default on cgroups v2 and create a new cgroup namespace.
When a cgroup namespace is used, processes inside the namespace are
only able to see cgroup paths relative to the cgroup namespace root
and not have full visibility on all the cgroups present on the
system.
The previous behaviour is maintained on a cgroups v1 host, where a
cgroup namespace is not created by default.
Closes: https://github.com/containers/libpod/issues/4363
Signed-off-by: Giuseppe Scrivano <gscrivan@redhat.com>
In commit 52df1fa (Fix volume handling in podman) was implemented the
--volume option for podman remove. However, its behaviour changed after
83db80c (Only remove image volumes when removing containers).
This commit updates the description of this option to reflect the new
behaviour.
Signed-off-by: Radostin Stoyanov <rstoyanov1@gmail.com>
change the default to -1, so that we can change the semantic of
"--tail 0" to not print any existing log line.
Closes: https://github.com/containers/libpod/issues/4396
Signed-off-by: Giuseppe Scrivano <gscrivan@redhat.com>
* Refactored code and Makefile to support new docs layout
* Removed some old code packaging code
* Add Readme.md to document what we're doing
Signed-off-by: Jhon Honce <jhonce@redhat.com>
Signed-off-by: baude <bbaude@redhat.com>
Restructuring the docs dir to make integration with sphinx easier. man
pages now exist in docs/source/man and the sphinx make files exists in
docs.
Signed-off-by: baude <bbaude@redhat.com>
Ed Santiago
OpenShift Merge Robot
Clint Olson
Valentin Rothberg
Daniel J Walsh
Boaz Shuster
Stefan Becker
Brent Baude
Matthew Heon
Qi Wang
Abhijeet Kasurde
Allan Jacquet-Cretides
Kir Kolyshkin
Matej Marusak
Matthew Heon
Robert P. J. Day
TomSweeneyRedHat
Sascha Grunert
Giuseppe Scrivano
Sorin Sbarnea
Mark Stosberg
Peter Hunt
José Guilherme Vanz
Kunal Kushwaha
Dmitry Smirnov
Jakub Filak
Radostin Stoyanov
Morten Linderud
Jhon Honce