diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/generate.go | 3 | ||||
| -rw-r--r-- | docs/podman-derivative-api | 4 | ||||
| -rw-r--r-- | docs/source/markdown/podman-build.1.md | 11 | ||||
| -rw-r--r-- | docs/source/markdown/podman-create.1.md | 21 | ||||
| -rw-r--r-- | docs/source/markdown/podman-run.1.md | 36 | ||||
| -rw-r--r-- | docs/tutorials/podman-derivative-api.md | 5 | ||||
| -rw-r--r-- | docs/tutorials/varlink_remote_client.md | 89 | ||||
| -rw-r--r-- | docs/varlink/apidoc.go | 279 |
8 files changed, 41 insertions, 407 deletions
diff --git a/docs/generate.go b/docs/generate.go deleted file mode 100644 index 2adca8fc1..000000000 --- a/docs/generate.go +++ /dev/null @@ -1,3 +0,0 @@ -package docs - -//go:generate go run varlink/apidoc.go ../pkg/varlink/io.podman.varlink ../API.md diff --git a/docs/podman-derivative-api b/docs/podman-derivative-api index 1b6153df5..2e085c248 100644 --- a/docs/podman-derivative-api +++ b/docs/podman-derivative-api @@ -52,10 +52,6 @@ Potential skew between multiple libpod versions operating on the same storage ca .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? diff --git a/docs/source/markdown/podman-build.1.md b/docs/source/markdown/podman-build.1.md index 4570bf3ff..c71f4fae9 100644 --- a/docs/source/markdown/podman-build.1.md +++ b/docs/source/markdown/podman-build.1.md @@ -317,6 +317,10 @@ Pass through HTTP Proxy environment variables. Write the image ID to the file. +#### **--ignorefile** + +Path to an alternative .dockerignore file. + #### **--ipc**=*how* Sets the configuration for IPC namespaces when handling `RUN` instructions. @@ -844,9 +848,10 @@ $ podman build -f dev/Containerfile https://10.10.10.1/podman/context.tar.gz ### `.dockerignore` -If the file .dockerignore exists in the context directory, `podman build` reads -its contents. Podman uses the content to exclude files and directories from -the context directory, when executing COPY and ADD directives in the +If the file .dockerignore exists in the context directory, `buildah copy` reads +its contents. Use the `--ignorefile` flag to override .dockerignore path location. +Podman uses the content to exclude files and directories from the context +directory, when executing COPY and ADD directives in the Containerfile/Dockerfile Users can specify a series of Unix shell globals in a .dockerignore file to diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md index f280087c2..ab390447e 100644 --- a/docs/source/markdown/podman-create.1.md +++ b/docs/source/markdown/podman-create.1.md @@ -1021,18 +1021,21 @@ The _options_ is a comma delimited list and can be: The `CONTAINER-DIR` must be an absolute path such as `/src/docs`. The volume will be mounted into the container at this directory. -Volumes may specify a source as well, as either a directory on the host or the -name of a named volume. If no source is given, the volume will be created as an -anonymous named volume with a randomly generated name, and will be removed when +Volumes may specify a source as well, as either a directory on the host +or the name of a named volume. If no source is given, the volume will be created as an +anonymously named volume with a randomly generated name, and will be removed when the container is removed via the `--rm` flag or `podman rm --volumes`. If a volume source is specified, it must be a path on the host or the name of a named volume. Host paths are allowed to be absolute or relative; relative paths -are resolved relative to the directory Podman is run in. Any source that does -not begin with a `.` or `/` will be treated as the name of a named volume. -If a volume with that name does not exist, it will be created. Volumes created -with names are not anonymous. They are not removed by the `--rm` option and the -`podman rm --volumes` command. +are resolved relative to the directory Podman is run in. If the source does not +exist, Podman will return an error. Users must pre-create the source files or +directories. + +Any source that does not begin with a `.` or `/` will be treated as the name of +a named volume. If a volume with that name does not exist, it will be created. +Volumes created with names are not anonymous, and they are not removed by the `--rm` +option and the `podman rm --volumes` command. You can specify multiple **-v** options to mount one or more volumes into a container. @@ -1069,7 +1072,7 @@ upper. Modifications to the mount point are destroyed when the container finishes executing, similar to a tmpfs mount point being unmounted. Subsequent executions of the container will see the original source directory -content, any changes from previous container executions no longer exists. +content, any changes from previous container executions no longer exist. One use case of the overlay mount is sharing the package cache from the host into the container to allow speeding up builds. diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md index d65d5d26f..13b586e17 100644 --- a/docs/source/markdown/podman-run.1.md +++ b/docs/source/markdown/podman-run.1.md @@ -1054,11 +1054,11 @@ Set the UTS namespace mode for the container. The following values are supported - **ns:[path]**: run the container in the given existing UTS namespace. - **container:[container]**: join the UTS namespace of the specified container. -#### **--volume**, **-v**[=[[_source-volume_|_host-dir_:]_container-dir_[:_options_]]] +#### **--volume**, **-v**[=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]*] -Create a bind mount. If you specify _/host-dir_:_/container-dir_, Podman -bind mounts _host-dir_ in the host to _container-dir_ in the Podman -container. Similarly, _source-volume_:_/container-dir_ will mount the volume +Create a bind mount. If you specify _/HOST-DIR_:_/CONTAINER-DIR_, Podman +bind mounts _host-dir_ in the host to _CONTAINER-DIR_ in the Podman +container. Similarly, _SOURCE-VOLUME_:_/CONTAINER-DIR_ will mount the volume in the host to the container. If no such named volume exists, Podman will create one. @@ -1073,24 +1073,30 @@ The _options_ is a comma delimited list and can be: <sup>[[1]](#Footnote1)</sup> * [**no**]**suid** * [**O**] -The _container-dir_ must be an absolute path. +The `CONTAINER-DIR` must be an absolute path such as `/src/docs`. The volume +will be mounted into the container at this directory. -Volumes may specify a source as well, as either a directory on the host or the -name of a named volume. If no source is given, the volume will be created as an -anonymous named volume with a randomly generated name, and will be removed when -the container is removed via the **--rm** flag or **podman rm --volumes**. +Volumes may specify a source as well, as either a directory on the host +or the name of a named volume. If no source is given, the volume will be created as an +anonymously named volume with a randomly generated name, and will be removed when +the container is removed via the `--rm` flag or `podman rm --volumes`. If a volume source is specified, it must be a path on the host or the name of a named volume. Host paths are allowed to be absolute or relative; relative paths -are resolved relative to the directory Podman is run in. Any source that does -not begin with a **.** or **/** will be treated as the name of a named volume. -If a volume with that name does not exist, it will be created. Volumes created -with names are not anonymous and are not removed by **--rm** and -**podman rm --volumes**. +are resolved relative to the directory Podman is run in. If the source does not +exist, Podman will return an error. Users must pre-create the source files or +directories. + +Any source that does not begin with a `.` or `/` will be treated as the name of +a named volume. If a volume with that name does not exist, it will be created. +Volumes created with names are not anonymous, and they are not removed by the `--rm` +option and the `podman rm --volumes` command. You can specify multiple **-v** options to mount one or more volumes into a container. + `Write Protected Volume Mounts` + You can add **:ro** or **:rw** option to mount a volume in read-only or read-write mode, respectively. By default, the volumes are mounted read-write. @@ -1119,7 +1125,7 @@ upper. Modifications to the mount point are destroyed when the container finishes executing, similar to a tmpfs mount point being unmounted. Subsequent executions of the container will see the original source directory -content, any changes from previous container executions no longer exists. +content, any changes from previous container executions no longer exist. One use case of the overlay mount is sharing the package cache from the host into the container to allow speeding up builds. diff --git a/docs/tutorials/podman-derivative-api.md b/docs/tutorials/podman-derivative-api.md index 8a1f40fc0..e38c2b13d 100644 --- a/docs/tutorials/podman-derivative-api.md +++ b/docs/tutorials/podman-derivative-api.md @@ -46,11 +46,6 @@ Disadvantages: - Binary size - Potential skew between multiple libpod versions operating on the same storage can cause problems -Varlink ---- - -The Varlink API is presently deprecated. We do not recommend adopting it for new projects. - Making the choice --- diff --git a/docs/tutorials/varlink_remote_client.md b/docs/tutorials/varlink_remote_client.md deleted file mode 100644 index 54c648a48..000000000 --- a/docs/tutorials/varlink_remote_client.md +++ /dev/null @@ -1,89 +0,0 @@ -# Podman varlink remote-client tutorial [DEPRECATED] - -## What is the varlink client - -This API has been deprecated by the [REST API](https://docs.podman.io/en/latest/_static/api.html). -For usage on Windows and Mac, please reference the [Podman Mac/Windows tutorial](https://github.com/containers/podman/blob/master/docs/tutorials/mac_win_client.md) -Varlink support is in maintenance mode, and will be removed in a future release. -For more details, you can see [this blog](https://podman.io/blogs/2020/01/17/podman-new-api.html). - -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 Podman 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/podman/blob/master/install.md) and follow the -section [Building from scratch](https://github.com/containers/podman/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 - -Varlink bridge support is provided by the varlink cli command and installed using: -``` -$ sudo dnf install varlink-cli -``` - -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, an ssh connection to the Podman server must be established. - -Using the varlink bridge, an ssh tunnel must be initiated to connect to the server. Podman must then be informed of the location of the sshd server on the targeted server - -``` -$ export PODMAN_VARLINK_BRIDGE=$'ssh -T -p22 root@remotehost -- "varlink -A \'podman varlink \$VARLINK_ADDRESS\' bridge"' -$ 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 -``` - -The PODMAN_VARLINK_BRIDGE variable may be added to your log in settings. It does not change per connection. - -If coming from a Windows machine, the PODMAN_VARLINK_BRIDGE is formatted as: -``` -set PODMAN_VARLINK_BRIDGE=C:\Windows\System32\OpenSSH\ssh.exe -T -p22 root@remotehost -- varlink -A "podman varlink $VARLINK_ADDRESS" bridge -``` - -The arguments before the `--` are presented to ssh while the arguments after are for the varlink cli. The varlink arguments should be copied verbatim. - - `-p` is the port on the remote host for the ssh tunnel. `22` is the default. - - `root` is the currently supported user, while `remotehost` is the name or IP address of the host providing the Podman service. - - `-i` may be added to select an identity file. diff --git a/docs/varlink/apidoc.go b/docs/varlink/apidoc.go deleted file mode 100644 index 87304de15..000000000 --- a/docs/varlink/apidoc.go +++ /dev/null @@ -1,279 +0,0 @@ -package main - -import ( - "bytes" - "fmt" - "io/ioutil" - "os" - "sort" - "strings" - - "github.com/varlink/go/varlink/idl" -) - -func readFileToString(path string) (string, error) { - content, err := ioutil.ReadFile(path) - if err != nil { - return "", err - } - return string(content), nil -} - -func exit(err error) { - fmt.Println(err.Error()) - os.Exit(1) -} - -func typeToString(input *idl.Type) string { - switch input.Kind { - case idl.TypeString: - return "string" - case idl.TypeBool: - return "bool" - case idl.TypeFloat: - return "float" - case idl.TypeArray: - result := input.ElementType.Alias - if result == "" { - return fmt.Sprintf("[]%s", typeToString(input.ElementType)) - } - return result - case idl.TypeAlias: - return input.Alias - case idl.TypeMap: - return "map[string]" - case idl.TypeInt: - return "int" - case idl.TypeMaybe: - return fmt.Sprintf("?%s", typeToString(input.ElementType)) - } - return "" -} - -func typeToLink(input string) string { - switch input { - case "string": - return "https://godoc.org/builtin#string" - case "int": - return "https://godoc.org/builtin#int" - case "bool": - return "https://godoc.org/builtin#bool" - case "float": - return "https://golang.org/src/builtin/builtin.go#L58" - default: - return fmt.Sprintf("#%s", input) - } -} - -type funcArgs struct { - paramName string - paramKind string -} -type funcDescriber struct { - Name string - inputParams []funcArgs - returnParams []funcArgs - doc string -} - -type funcSorter []funcDescriber - -func (a funcSorter) Len() int { return len(a) } -func (a funcSorter) Swap(i, j int) { a[i], a[j] = a[j], a[i] } -func (a funcSorter) Less(i, j int) bool { return a[i].Name < a[j].Name } - -type typeAttrs struct { - Name string - AttrType string -} -type typeDescriber struct { - Name string - doc string - Attrs []typeAttrs -} - -type typeSorter []typeDescriber - -func (a typeSorter) Len() int { return len(a) } -func (a typeSorter) Swap(i, j int) { a[i], a[j] = a[j], a[i] } -func (a typeSorter) Less(i, j int) bool { return a[i].Name < a[j].Name } - -type err struct { - Name string - doc string -} - -type errorSorter []err - -func (a errorSorter) Len() int { return len(a) } -func (a errorSorter) Swap(i, j int) { a[i], a[j] = a[j], a[i] } -func (a errorSorter) Less(i, j int) bool { return a[i].Name < a[j].Name } - -// collects defined types in the idl -func getTypes(tidl *idl.IDL) []typeDescriber { - var types []typeDescriber - for _, x := range tidl.Aliases { - i := typeDescriber{ - Name: x.Name, - doc: x.Doc, - } - ta := []typeAttrs{} - for _, y := range x.Type.Fields { - result := typeToString(y.Type) - ta = append(ta, typeAttrs{Name: y.Name, AttrType: result}) - } - i.Attrs = ta - types = append(types, i) - } - return types -} - -// collects defined methods in the idl -func getMethods(midl *idl.IDL) []funcDescriber { - var methods []funcDescriber - for _, t := range midl.Methods { - m := funcDescriber{ - Name: t.Name, - doc: t.Doc, - } - fa := []funcArgs{} - fo := []funcArgs{} - - for _, i := range t.In.Fields { - fa = append(fa, funcArgs{paramName: i.Name, paramKind: typeToString(i.Type)}) - - } - for _, f := range t.Out.Fields { - fo = append(fo, funcArgs{paramName: f.Name, paramKind: typeToString(f.Type)}) - } - m.inputParams = fa - m.returnParams = fo - methods = append(methods, m) - } - return methods -} - -// collects defined errors in the idl -func getErrors(midl *idl.IDL) []err { - var errors []err - for _, e := range midl.Errors { - myError := err{ - Name: e.Name, - doc: e.Doc, - } - errors = append(errors, myError) - } - return errors -} - -// generates the index for the top of the markdown page -func generateIndex(methods []funcDescriber, types []typeDescriber, errors []err, b bytes.Buffer) bytes.Buffer { - // Sort the methods, types, and errors by alphabetical order - sort.Sort(funcSorter(methods)) - sort.Sort(typeSorter(types)) - sort.Sort(errorSorter(errors)) - - for _, method := range methods { - var inArgs []string - var outArgs []string - for _, inArg := range method.inputParams { - inArgs = append(inArgs, fmt.Sprintf("%s: %s", inArg.paramName, inArg.paramKind)) - - } - for _, outArg := range method.returnParams { - outArgs = append(outArgs, outArg.paramKind) - - } - b.WriteString(fmt.Sprintf("\n[func %s(%s) %s](#%s)\n", method.Name, strings.Join(inArgs, ", "), strings.Join(outArgs, ", "), method.Name)) - } - b.WriteString("\n") - for _, t := range types { - b.WriteString(fmt.Sprintf("[type %s](#%s)\n\n", t.Name, t.Name)) - } - for _, e := range errors { - b.WriteString(fmt.Sprintf("[error %s](#%s)\n\n", e.Name, e.Name)) - } - return b -} - -// performs the output for defined methods -func generateFuncDescriptions(methods []funcDescriber, b bytes.Buffer) bytes.Buffer { - for _, method := range methods { - b.WriteString(fmt.Sprintf("### <a name=\"%s\"></a>func %s\n", method.Name, method.Name)) - var inArgs []string - var outArgs []string - for _, inArg := range method.inputParams { - inArgs = append(inArgs, fmt.Sprintf("%s: [%s](%s)", inArg.paramName, inArg.paramKind, typeToLink(inArg.paramKind))) - } - for _, outArg := range method.returnParams { - outArgs = append(outArgs, fmt.Sprintf("[%s](%s)", outArg.paramKind, typeToLink(outArg.paramKind))) - } - b.WriteString(fmt.Sprintf("<div style=\"background-color: #E8E8E8; padding: 15px; margin: 10px; border-radius: 10px;\">\n\nmethod %s(%s) %s</div>", method.Name, strings.Join(inArgs, ", "), strings.Join(outArgs, ", "))) - b.WriteString("\n") - b.WriteString(method.doc) - b.WriteString("\n") - } - return b -} - -// performs the output for defined types/structs -func generateTypeDescriptions(types []typeDescriber, b bytes.Buffer) bytes.Buffer { - for _, t := range types { - b.WriteString(fmt.Sprintf("### <a name=\"%s\"></a>type %s\n", t.Name, t.Name)) - b.WriteString(fmt.Sprintf("\n%s\n", t.doc)) - for _, i := range t.Attrs { - b.WriteString(fmt.Sprintf("\n%s [%s](%s)\n", i.Name, i.AttrType, typeToLink(i.AttrType))) - } - } - return b -} - -// performs the output for defined errors -func generateErrorDescriptions(errors []err, b bytes.Buffer) bytes.Buffer { - for _, e := range errors { - b.WriteString(fmt.Sprintf("### <a name=\"%s\"></a>type %s\n", e.Name, e.Name)) - b.WriteString(fmt.Sprintf("\n%s\n", e.doc)) - } - return b -} - -func main() { - args := os.Args - if len(args) < 2 { - exit(fmt.Errorf("you must provide an input and output path")) - } - varlinkFile := args[1] - mdFile := args[2] - - varlinkInput, err := readFileToString(varlinkFile) - if err != nil { - exit(err) - } - varlinkInput = strings.TrimRight(varlinkInput, "\n") - - // Run the idl parser - midl, err := idl.New(varlinkInput) - if err != nil { - exit(err) - } - // Collect up the info from the idl - methods := getMethods(midl) - types := getTypes(midl) - errors := getErrors(midl) - - out := bytes.Buffer{} - out.WriteString(fmt.Sprintf("# %s\n", midl.Name)) - out.WriteString(fmt.Sprintf("%s\n", midl.Doc)) - out.WriteString("## Index\n") - out = generateIndex(methods, types, errors, out) - out.WriteString("## Methods\n") - out = generateFuncDescriptions(methods, out) - out.WriteString("## Types\n") - out = generateTypeDescriptions(types, out) - out.WriteString("## Errors\n") - out = generateErrorDescriptions(errors, out) - if err := ioutil.WriteFile(mdFile, out.Bytes(), 0755); err != nil { - fmt.Fprintf(os.Stderr, "Error writing file: %v\n", err) - os.Exit(1) - } -} |