JDK-8238588 : JEP 380: Unix-Domain Socket Channels
  • Type: JEP
  • Component: core-libs
  • Sub-Component: java.nio
  • Priority: P3
  • Status: Closed
  • Resolution: Delivered
  • Fix Versions: 16
  • Submitted: 2020-02-06
  • Updated: 2021-06-29
  • Resolved: 2021-02-10
Related Reports
Relates :  
Sub Tasks
JDK-8241305 :  
JDK-8245194 :  
JDK-8253929 :  
JDK-8262130 :  

Add Unix-domain (`AF_UNIX`) socket support to the [socket channel][socketchannel] and [server-socket channel][serversocketchannel] APIs in the `java.nio.channels` package. Extend the [inherited channel mechanism][inherited] to support Unix-domain socket channels and server socket channels.

[socketchannel]: https://docs.oracle.com/en/java/javase/15/docs/api/java.base/java/nio/channels/SocketChannel.html

[serversocketchannel]: https://docs.oracle.com/en/java/javase/15/docs/api/java.base/java/nio/channels/ServerSocketChannel.html

[inherited]: https://docs.oracle.com/en/java/javase/15/docs/api/java.base/java/nio/channels/spi/SelectorProvider.html#inheritedChannel()


Unix-domain sockets are used for inter-process communication (IPC) on the same host. They are similar to TCP/IP sockets in most respects, except that they are addressed by filesystem path names rather than Internet Protocol (IP) addresses and port numbers. The goal of this JEP is to support all of the features of Unix-domain sockets that are common across the major Unix platforms and Windows. Unix-domain socket channels will behave the same as existing TCP/IP channels in terms of read/write behavior, connection setup, acceptance of incoming connections by servers, multiplexing with other non-blocking selectable channels in a selector, and support of relevant socket options.


It is not a goal to support features that are not common across the major Unix platforms and  Windows. This includes Linux-specific features such as the abstract filesystem-independent namespace. It also includes features that are generally supported on Unix but unsupported on Windows, such as socket pairs. Support for these features can be revisited in the future if needed and, in the case of the missing Windows features, if the Windows platform evolves to support them. An exception to this non-goal is support for peer credentials, which can be implemented as a JDK specific socket option on platforms that support it. Other socket options may be investigated as follow up work, possibly also as JDK specific options, after this JEP is completed.


For local, inter-process communication, Unix-domain sockets are both more secure and more efficient than TCP/IP loopback connections.

  - Unix-domain sockets are strictly for communication between processes on the same system. Applications that are not intended to accept remote connections can improve security by using Unix-domain sockets.

  - Unix-domain sockets are further protected by operating-system enforced, filesystem-based access controls.

  - Unix-domain sockets have faster setup times and higher data throughput than TCP/IP loopback connections.

  - Unix-domain sockets may be a better solution than TCP/IP sockets for container environments, where communication between containers on the same system is required. This can be achieved using sockets located in shared volumes.

Unix-domain sockets have long been a feature of most Unix platforms, and are now supported in Windows 10 and Windows Server 2019.


To support Unix-domain socket channels we will add the following API elements:

  - A new socket address class, `java.net.UnixDomainSocketAddress`;

  - A `UNIX` constant value in the existing `java.net.StandardProtocolFamily` enum;

  - New `open` factory methods  on `SocketChannel` and `ServerSocketChannel` that specify the protocol family

  - Updates to the  `SocketChannel` and `ServerSocketChannel` specifications to specify how channels to Unix domain sockets behave.


An application could access `AF_UNIX` address structures and socket system calls directly, either via the Java Native Interface (JNI) or [Project Panama][panama]. Socket objects of this type would, however, not be compatible with the existing `SocketChannel` API and therefore could not be multiplexed with other selectable channels using the `Selector` API.

[panama]: https://openjdk.java.net/projects/panama/


Automatic unit tests will exercise the API and implementation. These tests will run on all supported Unix platforms and on multiple versions of Windows, including some that support Unix-domain sockets and some that do not.

Risks and Assumptions

Existing code that uses the `SocketChannel` and `ServerSocketChannel` classes often assumes that instances of `SocketAddress` returned by those APIs can be blindly cast to `InetSocketAddress`. This cast will fail with Unix-domain socket channels.

Please seek the endorsement of a Group or Area Lead (https://openjdk.java.net/projects/jdk/leads) in order to target this JEP.

https://bugs.openjdk.java.net/browse/JDK-8254996 will address changing UnixDomainCredentials to be a record type after integration of this JEP.

`record Credentials(UserPrincipal user, GroupPrincipal group) { }` could be explored too (once records are standard of course).

A JDK specific socket option is worth exploring for peer credentials. It could potentially return a ProcessHandle which currently supports pid and username at least.

The proposal looks good. There are a number of small of API details, and a number of implementation details, that will require discussion. I agree with [~fweimer] that the omission of peer credentials from a first release will be a surprise in some environments. We could potentially use ExtendedSocketOption to expose peer credentials as a JDK-specific, and read-only, socket option (equivalent to SO_PEERCRED or LOCAL_PEERCRED) on platforms that support this feature.

[~michaelm] I���ve edited the text to tighten the wording and, in particular, the motivation section. If this looks okay to you then please assign the issue to me and I���ll move it to Candidate.

I'm concerned that not adding support for peer credentials will trick developers into writing vulnerable services. I'm not sure if it is really possible to avoid them.