From 2ec34c62b019431c0edebead50b56ebafe70a67c Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Mon, 10 Aug 2015 12:07:20 -0700 Subject: [PATCH] runtime: Document container ID charset and uniqueness domain 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 #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]: https://github.com/opencontainers/specs/pull/87#discussion_r35828046 [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 Signed-off-by: W. Trevor King --- runtime.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/runtime.md b/runtime.md index be2045b58..c9da6af9a 100644 --- a/runtime.md +++ b/runtime.md @@ -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. @@ -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