diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..6e34f46 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) 2016 Christian Speckner, Mayflower GmbH + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..d9a32de --- /dev/null +++ b/README.md @@ -0,0 +1,87 @@ +# What is it? + +Docker-ls is a set of CLI tools for browsing and manipulating docker registries. + +## What registries are supported + +Only V2 registries are supported. Both HTTP basic auth and docker style +[token authentication](https://github.com/docker/distribution/blob/master/docs/spec/auth/token.md) +are supported for authentication. + +# Installation + +TODO + +# Usage + +Docker-ls contains two CLI tools: `docker-ls` and `docker-rm` . The following paragraphs +give an overview over their usage; please consult the CLI help (option `-h`) for +more details. + +## docker-ls + +`docker-ls` is capable of browsing docker registries. Three subcommands are available + + * `docker-ls repositories`: Obtains a list of repositories on the server. + **This is not supported by the official docker hub.** + * `docker-ls tags`: Lists all tags in a a particular repository. + * `docker-ls tag`: Inspect a particular tag. This command displays a condensed version + of the corresponding manifest by default, but the `--raw-manifest` option can be + used to dump the full manifest. The `--parse-history` option can be used to display + the JSON-encoded history within the manifest. + +### Important command line flags + +This list is not comprehensive; please consult the command line (`-h`) help for all options. + + * `--registry ` Connect to the registry at URL. The URL must include the protocol + (http / https). + * `--user ` Username for authentication. + * `--password ` Password for authentication. + * `--level ` The `repositories` and `tags` subcommands support the level option + for recursing into more details. Depth 0 (default) and 1 are supported. Please note + the recursing means more requests and is slower. + * `--json` Switch output format from YAML to JSON. + * `--basic-auth` Use HTTP basic auth for authentication (instead of token authentication). + * `--allow-insecure` Do not validate SSL certificates (useful for registries secured with a + self-signed cert). + +### Examples + +List all repositories in a custom registry: + + docker-ls repositories --registry https://my.registry.org --user hanni --password hanni123 + +List all repositories in a custom registry, including their tags: + + docker-ls repositories --registry https://my.registry.org --user hanni --password hanni123 --level 1 + +List all tags in stuff/busybox using HTTP basic auth + + docker-ls tags --registry https://my.registry.org --user hanni --password hanni123 --basic-auth stuff/busybox + +Inspect tag stuff/busybox:latest, no authentication, JSON outut. + + docker-ls tag --registry https://my.registry.org --json stuff/busybox:latest + + +Inspect tag stuff/busybox:latest, no authentication, dump the raw manifest with parsed +history as JSON. + + docker-ls tag --registry https://my.registry.org --json --raw-manifest --parse-history stuff/busybox:latest + +## docker-rm + +`docker-rm` can delete particular tags. Example: + + docker-rm --registry https://foo.bar.org --user someuser --password somepass busybox/sha256:51fef[...] + +(the sha256 has been truncated for brevity). Please consult the command line help +for a full list of all arguments. + +Some remarks: + + * The tag *must* be specified as a content sha256. + * While tags can be deleted, the current registry implementation will (to the best + of my knowledge) not free the space associated with any now-unused layers. + * **BE CAREFUL!** The API does not implement undelete :) diff --git a/cli/docker-rm/main.go b/cli/docker-rm/main.go index 41649a2..91bdc78 100644 --- a/cli/docker-rm/main.go +++ b/cli/docker-rm/main.go @@ -8,7 +8,7 @@ import ( "git.mayflower.de/vaillant-team/docker-ls/lib" ) -const USAGE_TEMPLATE = `usage: [options] docker-rm +const USAGE_TEMPLATE = `usage: docker-rm [options] Delete a tag in a given repository. diff --git a/lib/auth/authenticator.go b/lib/auth/authenticator.go index 2f1972d..9bfac6a 100644 --- a/lib/auth/authenticator.go +++ b/lib/auth/authenticator.go @@ -49,7 +49,7 @@ func (a *authenticator) Authenticate(c *Challenge, ignoreCached bool) (t Token, } if authResponse.StatusCode != http.StatusOK { - err = errors.New(fmt.Sprintf("authentification against auth server failed with code %d", authResponse.StatusCode)) + err = errors.New(fmt.Sprintf("authentication against auth server failed with code %d", authResponse.StatusCode)) return }