[Feature] Listen on Unix socket

[mpfaff]

I have searched the existing feature requests, both open and closed, to make sure this is not a duplicate request.

• Yes

The feature

Currently, Immich only allows listening on an interface and port. However, the nodejs listen function called by Immich supports Unix sockets just by passing the file path to the socket. If Immich did not validate the type of the IMMICH_PORT config field, it should in theory be possible to just pass the path to the socket in there, not specify IMMICH_HOST, and have everything work fine. Unfortunately, Immich does check that this field contains an integer and doesn't provide a dedicated mechanism for listening on a Unix socket instead.

Obviously, a dedicated mechanism would be better than removing this validation. Therefore, I propose adding a new IMMICH_UNIX_SOCKET environment variable that, if set, will be listened to instead of an interface and port.

Platform

• Server
• Web
• Mobile

[Domini]

I'd like to add motivation as the original poster only described what, not why.

It would be cool to support listening on Unix domain socket for cases where for security reasons immich is placed behind reverse proxy either for ACL or TLS termination.

At the moment one has to expose immich on a TCP port which widens attack surface even if inside container using 127.0.0.1 (which itself increases complexity* and attack surface as immich must then share network namespace with the reverse proxy; Unix domain socket can be shared in a very targeted manner via a shared tmpfs volume without sharing anything else).

Please, give this feature some love, especially if its implementation is as easy as the original poster suggests.

* besides complexity it also makes certain security mitigations impossible

[mpfaff]

@Domini your use case is exactly what I had in mind myself! Thank you for sharing!

[Domini]

Let me briefly describe state of the union regarding support of UDS across all the Immich parts as of v3.0.3 while it's still fresh in my mind.

In summary it's possible to deploy Immich within one server almost fully air-gapped - mostly conceptually right air-gapped and partly with some hacks. Immich is ready to be fully air-gapped as in it does not require access to internet, but it does not support listening or consuming UDS everywhere yet to realize this goal without hacks.

I will quote excerpts from my own deployment, but bear in mind that I deployed it in Podman, hardened it quite a bit (e.g. replaced docker.io/valkey/valkey to dhi.io/valkey so e.g. user inside container changed and you might not be able to copy-paste as is), but it should point you a way and be easily reproducible in Docker.

immich-redis can listen on socket (--port 0 --unixsocket /dev/shm/valkey-socket/valkey.sock --unixsocketgroup nonroot --unixsocketperm 600), share this socket with immich-server and point to it using REDIS_SOCKET=/dev/shm/valkey-socket/valkey.sock. After that immich-redis can work with --network none.

This breaks immich-redis default HEALTHCHECK, it should be altered to [ "redis-cli", "-s", "/dev/shm/valkey-socket/valkey.sock", "-e", "ping" ]

immich-postgres can listen on socket (-c config_file=/etc/postgresql/postgresql.conf -c listen_addresses='' -k /var/run/postgresql -c unix_socket_permissions=0600), share this socket with immich-server and point to it using DB_URL=socket://postgres:password@/dev/shm/postgres-socket?db=immich. After that immich-postgres can work with --network none.

DB_URL=socket://postgres:password@/dev/shm/postgres-socket?db=immich currently breaks backup functionality, but the issue is not complex to fix.

immich-ml can listen on socket with a hack (--env IMMICH_HOST=unix:/dev/shm/ml-socket/ml.sock --env IMMICH_PORT=0) - the socket would be /dev/shm/ml-socket/ml.sock:0 (note :0 in the end). It's a hack because immich-ml sincerely thinks it listens on host and port, it's just the code does not do enough checks and passing unix socket there works.

This breaks immich-ml default HEALTHCHECK, it should be altered to [ "python3", "-c", "import os; import sys; import httpx; host = os.getenv('IMMICH_HOST', '0.0.0.0'); port = os.getenv('IMMICH_PORT', 3003); host = host.removeprefix('unix:'); transport = httpx.HTTPTransport(uds=f'{host}:{port}'); client = httpx.Client(transport=transport); response = client.get('http://localhost/ping'); sys.exit(0 if response.status_code == 200 else 1)" ].

Unfortunately, this socket cannot be consumed by immich-server directly (yet), as immich-server uses NodeJS default fetch which does not support UDS. Good news is that it's fairly easy to implement as NodeJS default fetch is actually undici under the hood, and if one imports undici directly and uses fetch from undici, it's not complex to add UDS support.

Share this socket with reverse proxy and expose it as an http://yourhost/path or https://yourhost/path URL. Consume this URL in immich-server by passing --env IMMICH_MACHINE_LEARNING_URL=https://yourhost/path.

Note: immich-ml can easily be exposed with subpath on reverse proxy and path rewritten to / when proxying requests into the UDS.

Create a separate immich-ml-preload container similar to immich-ml sharing the same volume for storing models (/cache). Don't expose the socket from it, but allow it access to the network (no --network none). When the models you use change (including when you just setup Immich from scratch), stop the main immich-ml container and launch immich-ml-preload with corresponding models passed via environment variables (e.g. --env MACHINE_LEARNING_PRELOAD__CLIP__TEXTUAL=ViT-B-32__openai --env MACHINE_LEARNING_PRELOAD__CLIP__VISUAL=ViT-B-32__openai --env MACHINE_LEARNING_PRELOAD__FACIAL_RECOGNITION__RECOGNITION=buffalo_l --env MACHINE_LEARNING_PRELOAD__FACIAL_RECOGNITION__DETECTION=buffalo_l --env MACHINE_LEARNING_PRELOAD__OCR__RECOGNITION=PP-OCRv5_server --env MACHINE_LEARNING_PRELOAD__OCR__DETECTION=PP-OCRv5_server) - let it download the models to /cache. Stop immich-ml-preload container.

Now you can air-gap immich-ml with --network none as models are already in its /cache and it does not need access to internet.

(In my setup immich-server Wants= immich-ml but does not Requires= or Before/After= it, and immich-ml-preload Conflicts= with immich-ml, so they can never run at the same time by design.)

Unfortunately, as this feature request postulates, immich-server itself cannot listen on UDS. So immich-server cannot be air-gapped with --network none. Expose immich-server via reverse proxy and let reverse proxy... proxy to http://immich-server-IP-address:2283. Subpath is not supported, Immich must be at the root of the (sub)domain (/). Now immich-server only needs to be able to accept connections from the reverse proxy IP for itself, and send requests to reverse proxy IP to reach immich-ml via reverse proxy. Firewall everything else, so immich-server does not have access anywhere else, even to your internal network.

If immich-ml is reverse proxied at (sub)domain and not IP address, immich-server needs to be able to resolve it. Just --add-host this domain to immich-server (or more complex - let only DNS requests through firewall).

After that you have fully conceptually properly air-gapped immich-redis, immich-postgres, fully properly air-gapped with a hack immich-ml, and almost fully air-gapped immich-server that only needs to be able to reach your internal reverse proxy.

Of course, certain functionality of Immich that requires internet access by design will not work after such brute force air-gapping, such as Google Cast, email notifications, Map feature (Reverse Geocoding works), and Version Check. Also, there is a red text in the left bottom corner "Server Offline - Unknown" that affects nothing. Some if not most of these features can be enabled back in a targeted manner.

CC FYI @mmomjian.

[bo0tzz]

IMO air-gapped doesn't necessarily mean that the application isn't even touching any network sockets, just that there is no possible path between it and the internet - which Immich can definitely do today.

[Domini]

Formally speaking, yes, after all I could not air-gap all the parts with just UDS and --network none and had to resort to firewalling.

Though e.g. if you firewall everything properly with src-address=immich-IP but e.g. forget to enable protections from spoofing, someone might gain remote access to the container, change IP address and now they have access to your network and the internet.

There are of course mitigations against all of it here or there, but having no network at all (--network none) and no exposed network attack surface is kind of a silver bullet. (E. g. now immich-server must listen on plaintext http (it does not support TLS termination, it's not even about complexity of setting it up), and I must trust that MITM cannot listen to my traffic between Immich and reverse proxy. There is simply no conceptual way to protect from it.)

UDS resolves this problem (support for TLS termination on immich-server too, but then we have double TLS if we use reverse proxy, and we want to use reverse proxy towards internet as reverse proxies are much more battle tested in this one task they're created for than each product whose main task is not TLS termination separately).

P.S. Of course, for example, if you need to deploy different parts of Immich machinery on different servers, UDS are no longer applicable.

[Domini]

BTW, that being said, it's not criticism of Immich. Amazing product. To be honest, I'm kinda surprised how prepared all the parts separately and together were to air-gapping, even if not ideal.

But this is a case study why the feature request exists. :)