Web interface to manage email aliases

[scheidti]

Hi community,

I’m excited to share an addon I’ve developed for DMS. It’s called Docker Mailserver Aliases, and it provides a simple web interface to manage email aliases! I developed it for my own DMS instance to easily create and delete email aliases.

For now this are the implemented features:

• List existing aliases: Easily view all email aliases and their forwarding addresses.
• Add new aliases: Create new email aliases.
• Delete aliases: Remove any unwanted or outdated aliases.

You can run it as a Docker container alongside Docker Mailserver.

Maybe someone will find it useful, and I’d love to get feedback!

[casperklein]

I couldn't get it to work. After startup, the mailserver-alias container immediately exits: mailserver-aliases-1 exited with code 0

Here is the demo setup I used:

compose.yaml

services:
  mailserver:
    hostname: mail.example.com
    image: ghcr.io/docker-mailserver/docker-mailserver:latest
    configs:
      - source: dms-account
        target: /tmp/docker-mailserver/postfix-accounts.cf

  mailserver-aliases:
    image: chscheid/docker-mailserver-aliases:1.0.1
    restart: unless-stopped
    environment:
      - GIN_ADDR=8080
    ports:
      - "8080:8080"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

# NOTE: This feature requires Docker Compose v2.23.1 (Nov 2023) or newer:
# https://github.com/compose-spec/compose-spec/pull/446
configs:
  # DMS requires an account to complete setup
  # password is `secret`
  dms-account:
    content: |
      jane.doe@example.com|{SHA512-CRYPT}$$6$$sbgFRCmQ.KWS5ryb$$EsWrlYosiadgdUOxCBHY0DQ3qFbeudDhNMqHs6jZt.8gmxUwiLVy738knqkHD4zj4amkb296HFqQ3yDq4UXt8.

---

Two thoughts:

1. Mounting /var/run/docker.sock gives the container full access to the docker daemon. This is bad from a security point of view (allowing the container to control every container, running additional containers etc.). Instead you could install a SSH daemon in the DMS container and issue the commands via ssh.
2. If I understand correctly, DMS is detected by the used image name. If DMS is run with a custom image build (with a different image name), it does not work? The container name could be configurable via an ENV.

[polarathene]

Then you have just shifted the risk from one container to another.

Yeah, I'm not exactly fond of it being tacked on to an alpine image with shell access, but it is just a reverse-proxy (HAProxy). I could put together the same with Caddy I think and create an image that is a bit more secure by throwing away everything else not needed in the image 😅

There's still a benefit from the indirection, which complicates the effort to attack and compromise the socket (notably when there's more than one container wanting socket access).

Unfortunately they don't offer a way to manage permissions for different scopes, so multiple proxy services need to be run if sharing the same permissions isn't appropriate.

---

EDIT: I looked through the docker-socket-proxy project and existing issues along with some past closed ones and merged PR history and wasn't too fond of what I was seeing. I think I'd rather just build the equivalent with Caddy tbh.

[polarathene]

If you/Georg agree, I could integrated a small HTTP server (disabled by default) based on the example above into DMS.

I am reluctant, we have a separate API repo that was meant to build towards that but stalled. If someone wants to run a service like you've proposed in DMS they should build the executable and add the supervisord config themselves rather than us maintaining an official one that starts getting depended on by other projects if we're not able to commit the time to approach it properly 😓

While not as small, similar could be done and maybe a bit more accessible with Caddy and the caddy-exec plugin (though there is a bug that'd need to be addressed, not quite sure how well maintained the plugin is tbh). The token may help but not so much when it's going over HTTP instead of HTTPS, with Caddy the user has a bit more options including self-signed certs (or using the same certs that DMS has been provisioned with), you could also leverage forward auth or mTLS, along with trust by IP, etc.

So while less convenient, I'd suggest docs + feature request issue as usual so we know of explicit demand/interest instead of implicit. Personally I'd rather see the setup CLI (or at least portions of it like user management) ported away from shell scripts to Go or Rust which could then offer CLI + API options along with JSON responses which would be a bit more friendly to projects like @scheidti has made. This would better match the intended use-case too, and while unfortunately is much more effort it wouldn't add friction to maintaining DMS if it was later pursued when other users become dependent upon the stop gap solution from running any commands via HTTP.

---

UPDATE: For reference, I've documented a fully working Caddy proxy API via UDS with a compose.override.yaml.

[polarathene]

2. Make the image name configurable.

Rather than searching containers by filtering on the image name alone, you could use other heuristics like labels (on DMS for your image to identify) or even the DMS container name? (as an input configured to your image)

You could technically use this label too I think:

docker-mailserver/Dockerfile

Lines 332 to 333 in cace9c5

	# Add metadata to image:
	LABEL org.opencontainers.image.title="docker-mailserver"

Assuming that persists across custom builds that extend DMS 🤔

[audioscavenger]

guys, i hear you all screaming about docker.sock... My 2 cents are:

if you know anything about docker and are able to install dms and run it, you KNOW what risks are involved. I don't believe people who can do all the above are that dumb. Yes mounting the docker.sock gives access to other containers too... not the host tho... what risks are we even talking about...

That being said, I moved on and found a nice solution for dms-gui: python API. Still working on it but it's gonna work exactly the same as if you gave me docker.sock. AND you can limit the scope of the API moving forward! problem solved?

Simply add this to DMS compose:

• expose 8888
• env DMS_API_KEY=whatever is generated in dms-gui or your own, if so add it to dms-gui settings page
• +2 mounts:
  • ./config/dms-gui/user-patches-api.sh:/tmp/docker-mailserver/user-patches.sh:ro
  • ./config/dms-gui/user-patches-api.py:/tmp/docker-mailserver/user-patches-api.py:ro

pretty simple... all is required is agreement to mount my config sub-folder under ./config from DMS for sake of simplicity. or else, adapt the paths to where you want to save dms-gui config, you know how.

[polarathene]

I don't believe people who can do all the above are that dumb.

I think you've just contradicted yourself...

EDIT: You were already made aware of the risks to the host system previously too 🤔

---

Yes mounting the docker.sock gives access to other containers too... not the host tho... what risks are we even talking about...

If you run Docker as a rootful daemon, then access to the socket permits starting a container with whatever options you like... such as I don't know... --volume /:/host-root-fs for example.

If you are familiar at all with the exploits available for an attacker to gain control of the host system, this is one of those scenarios that enable that quite easily for the attacker to then escape from a container of their choosing to the host system and do whatever they like (since rootful containers may have root users that aren't equivalent to root on the host, once escaped that user is now the proper host root user).

This is not the case when you are running rootless containers with a socket to a rootless daemon. Or in the case of Podman, which has a perk AFAIK that Podman can run both rootful and rootless containers simultaneously, each with their own socket access. Regardless you need to be careful of such.

You'll also come across rootful containers that for convenience of users volume mounts run as UID/GID 1000 so that the files written to the bind mount volume don't clash with ownership belonging to root, and also cited as a security benefit by running as non-root. However, it's not uncommon for a user to have Docker installed and given passwordless sudo access for that user to call docker command (as root), such that gaining the ability to run the command as that user on the host provides the equivalent of root access, just like with the socket example.

These are concerns, like many others I'm aware of with Docker (or similar container engines) that a typical user of such is not often aware of the risks/caveats. Some partially are but hand-wave it away as a non-concern. If you use containers for isolation and security benefits, then these are not concerns to play down when running third-party software distributed by an individual (even when the individual themselves are trustworthy, there's other risk factors that can and have happened in the past).

There's a good reason that blindly giving full access to the docker socket (or similar) is heavily discouraged around the web. Please heed that advice 👍

That being said, I moved on and found a nice solution for dms-gui: python API.
Still working on it but it's gonna work exactly the same as if you gave me docker.sock.

Ok? Existing solutions were cited, along with mention of the DMS org having a repo for anyone interested in pushing forward a proper API (last few attempts were in Python btw).

If all you're going to do is forward CLI commands it's rather simple to do.

---

Feedback

Summary:

• Exposing ports is not required.
• Passing secrets through ENV is discouraged if it can be helped.
• user-patches.sh works, but you should probably configure a service as advised.

Simply add this to DMS compose:

* expose 8888

* env DMS_API_KEY=whatever is generated in dms-gui or your own, if so add it to dms-gui settings page

* +2 mounts:
  
  * ./config/dms-gui/user-patches-api.sh:/tmp/docker-mailserver/user-patches.sh:ro
  * ./config/dms-gui/user-patches-api.py:/tmp/docker-mailserver/user-patches-api.py:ro

• You don't need expose. That is informational only. Any container able to reach another over a connected network can do so without that to any port

  There was a vulnerability in Docker where it was possible to route traffic from one machine to another's docker host, even when that container didn't have ports published externally. I have a detailed report for that at moby, but I believe it's been resolved since_).

• Using an ENV for providing secrets to containerized services is discouraged. It is convenient, but it does expose that secret to any process in the container, and also any that is able to query a containers ENV (hello docker socket vulnerability).

  There's various other ways to provide secrets, but often reading from a file is a good option. That file can be secured with ownership / permissions set. Just keep in mind that locking that down properly is a bit more involved for both you and the user though (don't bother with Docker Compose feature for secrets or file mounts with UID/GID + mode settings as those don't work unless using Docker Swarm last I checked).

  Again, this is often a concern most are comfortable with not taking too seriously. It's far less damage/risk vs access to the docker socket, so I wouldn't worry about this too much I just wanted to make you aware of these caveats regarding security with ENV and secrets.

• Regarding your mounts.. user-patches.sh is a feature users do use in DMS, so while users can mount your script as user-patches.sh into DMS, they should just as easily be able to mount it under a different name and add a line to their own personal user-patches.sh to call your separately maintained script (so there's minimal hassle during upgrades and such, should changes ever occur).

  I have not seen what your user-patches.sh is doing, but if it's just to start a service... you have been advised earlier with a full working example of how to do just that with our supervisord process manager. It's just a different filename/location and a few lines to configure the service, no user-patches.sh needed and it integrates into DMS more smoothly (for example what happens if the user system briefly runs into an OOM event which has their system kill a process running in a container such as your own service started by user-patches.sh? This can and does happen, if it were configured as a service properly it could be restarted automatically for you)

  Additionally be mindful of bind mounting single files instead of the parent directories. It works, but sometimes causes caveats should anyone try to edit the file (host or container). Changes can be done provided the inode doesn't change, otherwise any sync of changes is broken between host and container. In your case that might not matter much in practice (other than perhaps a dev gotcha on your end whilst iterating).

---

I have a reply in progress already on this same topic with you elsewhere... (EDIT: Done, prior discussion history was here) I'd rather you didn't spread the conversation across different DMS discussions as you have been doing so lately. I'm not sure what value is being provided, especially when you've yet to materialize / finalize your approach 🤷‍♂️

[leoborlot]

I´ve build this interface, with access control, password recover and manager each email from each domain.

still working in progress and in pt-br language.
Any one intersted?

[leoborlot]

By the way, English is not my first language, so I might make some mistakes.

---

Good! This project is almost like a side project for me; I went up to the first checkpoint for the client and left new features to be developed when I have the time.

I completely understand and agree with you. The current format of DMS is very concise and is working well. Running everything locally in a file-based setup has made the project quite solid.

There are some exceptions when we need to interact with the data, but that’s expected when dealing with shell and file-based operations. Nothing that the project’s evolution won’t eventually resolve.

I personally don't see a strong need to open an API within DMS, as it serves a wide range of users, including those who prefer it to remain standalone and isolated.

The API I developed interacts with the container through the Docker Socket and Python's Docker library. It makes requests directly on the DMS container's shell, handling stdout and stderr to return JSON to the consumer (some times using regex to strutcture the json). Realy, at this api level, we need a database to manage access permissions, keys, and temporary data (such as password reset tokens, for example). Currently, I use MySQL, but considering portability, we could think about using SQLite, given the low database requirements. This way, we continue with the DMS project's encapsulated aspect.

I haven’t implemented OpenAPI yet; I followed a modular architecture with JWT authentication. I’ll study OpenAPI to assess its impact on the current project and will report back to see if it can be adopted.

I chose to build the frontend with React as I find it easier than doing it directly with Python. For frontend work, even PHP is easier than Python. React has some great component features for listings and routing. This specific frontend I would rebuild entirely, as it's been a year since then, and I was still maturing my knowledge of React at the time. But since it's a single page, I believe I will revisit it when I get to adding the basic features.

I think the project could indeed become open-source, even as a reinforcement for the DMS project, which has already solved a number of issues by delivering most of the needed features. I will review everything we discussed here and organize things so that this can be done.

[polarathene]

By the way, English is not my first language, so I might make some mistakes.

Yes I understand, that's ok! No worries 😎

---

The API I developed interacts with the container through the Docker Socket and Python's Docker library. It makes requests directly on the DMS container's shell, handling stdout and stderr to return JSON to the consumer (some times using regex to strutcture the json).

Oh ok, this is the approach @scheidti also chose, but with Go instead of Python.

---

Really at this API level, we need a database to manage access permissions, keys, and temporary data (such as password reset tokens, for example).
Currently, I use MySQL, but considering portability, we could think about using SQLite, given the low database requirements. This way, we continue with the DMS project's encapsulated aspect.

For permissions, this is not something DMS is suitable to handle. LDAP and OAuth2 are better at conveying that information and both are external.

As you are managing only for ACCOUNT_PROVISIONER=FILE support (?), you might want to handle permissions on your end with something like Permify. That is a language agnostic service suited for the task.

Password reset tokens is identity related, you can implement this functionality yourself, or use a service like Authelia (I think they have password reset support) which provides OAuth2 and can integrate with LDAP and file based configs of their own for accounts. Services like Authelia with OAuth2 / OIDC allows a user to share the same account login with DMS and your web UI with common metadata that could help with permissions.

That said OAuth2/OIDC support is limited in DMS, we still need to manage postfix-accounts.cf or LDAP. Services like Authelia would need to implement SCIM support, and DMS would also need this to have postfix-accounts.cf managed by the identity service instead. For now you would still need to manage postfix-accounts.cf or setup email ....

Currently, I use MySQL, but considering portability, we could think about using SQLite, given the low database requirements. This way, we continue with the DMS project's encapsulated aspect.

Database for accounts is a feature DMS has tried to avoid, but we may be able to add support in future. At least for now if you'd like to contribute docs for what changes are required and a feature request issue for users to express interest, that would help towards landing that integration.

I have basic example for Postgres with a compose.yaml that extends the DMS official image with needed package and config change for relay config: #4145 (comment) (it should be similar for other supported databases)

Your other needs for a database would probably need to be a separate database (or use the services I mentioned that have their own sqlite support for their needs).

---

I haven’t implemented OpenAPI yet; I followed a modular architecture with JWT authentication. I’ll study OpenAPI to assess its impact on the current project and will report back to see if it can be adopted.

That's ok, it is just a good practice as it is language agnostic and can generate some nice docs. It is also helpful for testing APIs with.

Many frameworks will have support to export OpenAPI schema. For example here is one for Flask that uses decorators in Python, and it's API docs generator support.

Since only your frontend will use your API for now, this is not too important, but it helps when the API is a separate service/container for others to also use. The OpenAPI schema can also be used to generate initial client code in different languages for easier adoption of your API.

---

I chose to build the frontend with React as I find it easier than doing it directly with Python. For frontend work, even PHP is easier than Python. React has some great component features for listings and routing.

React is a fine choice and I would endorse that, it is my preferred choice for building web UIs with.

I think the project could indeed become open-source, even as a reinforcement for the DMS project, which has already solved a number of issues by delivering most of the needed features. I will review everything we discussed here and organize things so that this can be done.

Great to hear!

If you're new to maintaining open-source projects, it can sometimes have some downsides vs private development. I would suggest starting with your own separate repo when you're ready, no rush to move it into the DMS organization 👍

Do update us with a link here should you publish to Github. If you have any queries for advice on how we do anything with CI or project maintenance with DMS that would interest you let me know.

[audioscavenger]

where is the repo?? I'd love to test it

[polarathene]

While not the repo you've asked for, there was another admin UI project you may be interested in knowing of mentioned with links at the end of this comment.

[audioscavenger]

so much activity around this UI idea, loving it!
However, I spent close to 100h on this dms-gui project and am gonna use it no matter what.
hopefully there is adoption, if not that's fine. At least I use it as a leverage to learn react.