Add explanation about `console-socket`

[utam0k]

What is the problem you're trying to solve
Hi! I've always found containerd useful.
I'm building my own oci-container runtime that works with containerd, and I had a lot of trouble with console-socket. I ended up reading and understanding the code of runc, crun and containerd. Is there any documentation about this somewhere? If not I'd be happy to help.

Describe the solution you'd like
If there is a document somewhere that summarizes the unique arguments to be passed to the oci container runtime, it is a good idea to describe them in that document.

Additional context

containerd/vendor/github.com/containerd/go-runc/console.go

Line 139 in 261c107

func (c *Socket) ReceiveMaster() (console.Console, error) {

[mikebrow]

I'd look this over some.. particularly the console portions in the config docs..https://github.com/opencontainers/runtime-spec

[utam0k]

@mikebrow
Thank you for your comment.
I looked at the oci-spec you gave me, but I couldn't find anything about console-socket. I'm sorry if I'm just missing something, please let me know.
Am I right in thinking that console-socket is passed as an argument to create instead of config.json, and that the file descriptor of the master of the pseudo-terminal and the name of the pty are passed?
Sorry if this is too newbie question.

[AkihiroSuda]

Is this doc helpful for you?

https://github.com/opencontainers/runc/blob/master/docs/terminals.md#detached-new-terminal

[utam0k]

@AkihiroSuda
Oh this document is very helpful. Thank you very much.
It seems like there should be a description of this in containerd, should I close this issue?
I'm sorry if I'm suggesting the wrong thing.

[kzys]

(Background: @utam0k has been developing https://github.com/containers/youki)

I'm unsure containerd is the right place regarding console-socket. runc is defining the interface and containerd is just following that. We are not the authoritative source regarding the parameter.

That being said, I don't know how other OCI runtimes (crun, runj, ...) maintain the compatibility with runc. As @utam0k mentioned, OCI Runtime spec doesn't cover the aspect.

[utam0k]

@kzys
Thanks for the explanation and comments. Oops, it was the opposite of what I had imagined.

I'm unsure containerd is the right place regarding console-socket. runc is defining the interface and containerd is just following that.

If it is close to the actual de facto standard, it may be more correct to describe it in oci spec, whether this is the best or not. However, the impact on podman may need to be considered.

We are not the authoritative source regarding the parameter.

As for youki which I develop there are many aspects to be understood by reading the runc code, including other developers. However, I couldn't imagine what to send or what console-socket is for, especially from its name, so I made an issue.

That being said, I don't know how other OCI runtimes (crun, runj, ...) maintain the compatibility with runc. As @utam0k mentioned, OCI Runtime spec doesn't cover the aspect.

I probably shouldn't have created this issue here, so I'll leave it for a few days and close it if there are no comments.

[samuelkarp]

The runtime spec doesn't really have much to say on this (or on some other things like the precise set of flags vs. positional arguments in the CLI). Effectively, runc ends up being the standard for portions of the spec that are undefined due to its popularity and status as the reference implementation.

I wrote up a bit about the console socket here and would be happy to work together on something that's more clear.

[kzys]

Oh, I thought that the spec is only covering the JSON payload. It is having a section regarding the subcommands (found from Sam's notes).

Ultimately, I think, we should revise the runtime spec to explain more about the flags and the positional arguments. The document currently has the note;

Note: these operations are not specifying any command-line APIs, and the parameters are inputs for general operations.

But why not? :)

[samuelkarp]

But why not? :)

I think @tianon might have some of the background, but my understanding is that there wasn't agreement on the command-line interfaces (parameters, arguments, inputs and outputs via STDIO, additional things like this console-socket, etc) at the time the spec was written and released as 1.0.0.

[tianon]

I think the historical "why not" is because at the time, we really wanted to avoid being too prescriptive on the specific UI / UX the various tools took, and felt like it was overstepping our role (if I'm recalling correctly -- I think there might be some ancient meeting recordings somewhere that could corroborate or contradict). There was definitely a lot of discussion around this for https://github.com/opencontainers/runtime-tools, which unfortunately didn't gather the same level of attention as the specification (or even the runc reference implementation), and as I recall the conclusion was that there would be wrappers for different runtimes to deal with UX differences in how different operations are performed.

[kzys]

Thanks @tianon and @samuelkarp.

I think, it would be better to revisit the discussion and I'm fine driving that if we can agree about the direction.

• Now we have multiple OCI runtimes (runc, crun, runsc, runj, youki, ...) and no compatibility wrappers as far as I know
• runc will have 1.0.0 release finally. If it follows semver (does it?), it has to have some sort of backward-compatibility guarantee. Documenting the spec would help.
• It would be prescriptive in some degree, but we could use MUST / MAY / SHOULD as like the current spec and IETF RFCs.

Thoughts?

[tianon]

I think, it would be better to revisit the discussion and I'm fine driving that if we can agree about the direction.

• Now we have multiple OCI runtimes (runc, crun, runsc, runj, youki, ...) and no compatibility wrappers as far as I know
• runc will have 1.0.0 release finally. If it follows semver (does it?), it has to have some sort of backward-compatibility guarantee. Documenting the spec would help.
• It would be prescriptive in some degree, but we could use MUST / MAY / SHOULD as like the current spec and IETF RFCs.

Thoughts?

An interesting idea -- I wonder if I can convince some other folks (perhaps a little closer to the "fire" so to speak) to opine on that who I'm hoping would have more realistic opinions than mine; @giuseppe @crosbymichael @kolyshkin @cyphar ? 😇 🙏