Skip to content

Commit

Permalink
runtime: Document container ID charset and uniqueness domain
Browse files Browse the repository at this point in the history
Allow the runtime to use it's own scheme, but let the caller use UUIDs
if they want.  Jonathan asked for clarification as part of opencontainers#87, but
didn't suggest a particular approach [1].  When we discussed it in the
2015-08-26 meeting [2], the consensus was to just allow everything.
With container IDs like 'a/b/c' leading to state entries like
'/var/oci/containers/a/b/c/state.json'.  But that could get ugly with
container IDs that contain '../' etc.  And perhaps there are some
filesystems out there that cannot represent non-ASCII characters
(actually, I'm not even sure what charset our JSON is in ;).  I'd
rather pick this minimal charset which can handle UUIDs, and make life
easy for runtime implementers and safe for bundle consumers at a
slight cost of flexibility for bundle-authors.

There was some confusion on the list about what "ASCII letters" meant
[3], so I've explicitly listed the allowed character ranges.  Here's a
Python 3 script that shows the associated Unicode logic:

  import unicodedata

  # http://www.unicode.org/reports/tr44/tr44-4.html#GC_Values_Table
  category = {
    'Ll': 'lowercase letter',
    'Lu': 'uppercase letter',
    'Nd': 'decimal number',
    'Pd': 'dash punctuation',
  }

  for i in range(1<<7):
      char = chr(i)
      abbr = unicodedata.category(char)
      if abbr[0] in ['L', 'N'] or abbr == 'Pd':
          cat = category[abbr]
          print('{:02x} {} {}'.format(i, char, cat))

[1]: opencontainers#87 (comment)
[2]: https://github.com/opencontainers/specs/wiki/Meeting-Minutes-2015-08-26
[3]: https://groups.google.com/a/opencontainers.org/d/msg/dev/P9gZBYhiqDE/-ptpOcQ5FwAJ
     Message-Id: <7ec9cff6-c1a6-4beb-82de-16eb412bf2f8@opencontainers.org>

Reported-by: Jonathan Boulle <jonathanboulle@gmail.com>
Signed-off-by: W. Trevor King <wking@tremily.us>
  • Loading branch information
wking committed Sep 14, 2015
1 parent dca1dfd commit 2ec34c6
Showing 1 changed file with 5 additions and 0 deletions.
5 changes: 5 additions & 0 deletions runtime.md
Expand Up @@ -11,6 +11,9 @@ By providing a default location that container state is stored external applicat

* **version** (string) Version of the OCI specification used when creating the container.
* **id** (string) ID is the container's ID.
Only ASCII letters, numbers, and hyphens are valid (a–z, A–Z, 0–9, and ‘-’).
This value must be unique for a given host, but need not be universally unique.
Runtimes must allow the caller to set this ID, so that callers may choose, for example, to use [UUIDs][uuid] for universal uniqueness.
* **pid** (int) Pid is the ID of the main process within the container.
* **root** (string) Root is the path to the container's bundle directory.

Expand Down Expand Up @@ -94,3 +97,5 @@ If a hook returns a non-zero exit code, then an error is logged and the remainin

`path` is required for a hook.
`args` and `env` are optional.

[uuid]: https://tools.ietf.org/html/rfc4122

0 comments on commit 2ec34c6

Please sign in to comment.