[GH-ISSUE #376] Consider Alternatives to exposing ports to Gerbil in Docker Compose #22710

New Issue

GiteaMirror · 2026-06-05T04:53:05-05:00

GiteaMirror commented

2026-06-05 04:53:05 -05:00

Originally created by @bannert1337 on GitHub (Mar 21, 2025).
Original GitHub issue: https://github.com/fosrl/pangolin/issues/376

Currently, to create a raw TCP/UDP resource the user has to manually expose ports to Gerbil in the Docker Compose.
This is cumbersome and error-prone.

An alternative could be to use network mode host for Gerbil.

Pros of using network mode: host for Gerbil:

Simplified Configuration: Users would no longer need to manually edit the Docker Compose file to expose ports for each raw TCP/UDP resource. This greatly simplifies the initial setup and reduces the burden on the user.
Reduced Error Proneness: Removing the manual port exposure step eliminates the risk of typos, incorrect port mappings, and forgetting to expose necessary ports, leading to a less error-prone configuration process.
More Straightforward User Experience: The setup becomes more intuitive and less technical for users who might not be familiar with Docker networking concepts. The process of adding raw TCP/UDP resources would become smoother and faster.

Cons of using network mode: host for Gerbil:

Security Implications: Running Gerbil in network mode: host significantly reduces network isolation. Gerbil will share the host machine's network namespace, meaning it can bind to any port on the host and could potentially interact with other services running directly on the host. This might be undesirable from a security perspective, especially in shared environments.
Port Conflicts: If Gerbil (or Pangolin functionalities relying on Gerbil) needs to use ports that are already in use by other processes running on the host machine (outside of Docker), port conflicts can occur. This would require manual port management and potentially reconfiguration of existing host services.
Reduced Container Isolation: Using network mode: host goes against the typical best practices of containerization, which emphasize process and network isolation. It makes the container less self-contained and more tightly coupled to the host environment.
Potential for Unexpected Host Network Interactions: Gerbil's unrestricted access to the host network through network mode: host could lead to unexpected interactions or dependencies on the host's network configuration, making the system less portable and predictable across different host environments.

Originally created by @bannert1337 on GitHub (Mar 21, 2025). Original GitHub issue: https://github.com/fosrl/pangolin/issues/376 Currently, to create a raw TCP/UDP resource the user has to manually expose ports to Gerbil in the Docker Compose. This is cumbersome and error-prone. An alternative could be to use network mode `host` for Gerbil. **Pros of using `network mode: host` for Gerbil:** * **Simplified Configuration:** Users would no longer need to manually edit the Docker Compose file to expose ports for each raw TCP/UDP resource. This greatly simplifies the initial setup and reduces the burden on the user. * **Reduced Error Proneness:** Removing the manual port exposure step eliminates the risk of typos, incorrect port mappings, and forgetting to expose necessary ports, leading to a less error-prone configuration process. * **More Straightforward User Experience:** The setup becomes more intuitive and less technical for users who might not be familiar with Docker networking concepts. The process of adding raw TCP/UDP resources would become smoother and faster. **Cons of using `network mode: host` for Gerbil:** * **Security Implications:** Running Gerbil in `network mode: host` significantly reduces network isolation. Gerbil will share the host machine's network namespace, meaning it can bind to any port on the host and could potentially interact with other services running directly on the host. This might be undesirable from a security perspective, especially in shared environments. * **Port Conflicts:** If Gerbil (or Pangolin functionalities relying on Gerbil) needs to use ports that are already in use by other processes running on the host machine (outside of Docker), port conflicts can occur. This would require manual port management and potentially reconfiguration of existing host services. * **Reduced Container Isolation:** Using `network mode: host` goes against the typical best practices of containerization, which emphasize process and network isolation. It makes the container less self-contained and more tightly coupled to the host environment. * **Potential for Unexpected Host Network Interactions:** Gerbil's unrestricted access to the host network through `network mode: host` could lead to unexpected interactions or dependencies on the host's network configuration, making the system less portable and predictable across different host environments.

GiteaMirror closed this issue

2026-06-05 04:53:06 -05:00

GiteaMirror commented

2026-06-05 04:53:09 -05:00

@bannert1337 commented on GitHub (Mar 21, 2025):

Alternative 2: Dynamic Port Allocation and Container Orchestration

Instead of network mode: host, Gerbil could be modified to dynamically request ports from the Docker daemon or an orchestrator (like Docker Swarm or Kubernetes, if Pangolin aims for broader deployment strategies).

Pros of Dynamic Port Allocation:

Users are relieved from manual port management. Gerbil could request a port from the Docker daemon when a new raw TCP/UDP resource is created and automatically configure Traefik and itself.
Docker or the orchestrator will handle port allocation, minimizing conflicts within the Docker environment itself.
The process of adding raw TCP/UDP resources would become fully automated and user-friendly, requiring no manual Docker Compose editing.

Cons of Dynamic Port Allocation:

Implementing dynamic port allocation in Gerbil and integrating it with Traefik and Pangolin would require significant development effort. It involves inter-container communication and coordination.
This approach becomes tightly coupled to the Docker API (or the specific orchestration platform's API). It might make Pangolin less portable to environments outside of Docker/orchestration.
While users don't manage ports, the ports still need to be exposed from the container to the host. Security considerations around port exposure still exist, although they are managed automatically.

@bannert1337 commented on GitHub (Mar 21, 2025): Alternative 2: Dynamic Port Allocation and Container Orchestration Instead of `network mode: host`, Gerbil could be modified to dynamically request ports from the Docker daemon or an orchestrator (like Docker Swarm or Kubernetes, if Pangolin aims for broader deployment strategies). **Pros of Dynamic Port Allocation:** * Users are relieved from manual port management. Gerbil could request a port from the Docker daemon when a new raw TCP/UDP resource is created and automatically configure Traefik and itself. * Docker or the orchestrator will handle port allocation, minimizing conflicts within the Docker environment itself. * The process of adding raw TCP/UDP resources would become fully automated and user-friendly, requiring no manual Docker Compose editing. **Cons of Dynamic Port Allocation:** * Implementing dynamic port allocation in Gerbil and integrating it with Traefik and Pangolin would require significant development effort. It involves inter-container communication and coordination. * This approach becomes tightly coupled to the Docker API (or the specific orchestration platform's API). It might make Pangolin less portable to environments outside of Docker/orchestration. * While users don't manage ports, the ports still need to be exposed from the container to the host. Security considerations around port exposure still exist, although they are managed automatically.

GiteaMirror commented

2026-06-05 04:53:11 -05:00

@bannert1337 commented on GitHub (Mar 21, 2025):

Alternative 3: Dedicated Proxy Container within a Docker Network

Keep Gerbil in a standard Docker bridge network or a dedicated network. Introduce a separate, lightweight "proxy" container within the same network. This proxy container would be responsible for exposing the ports to the host. Gerbil would configure this proxy container via an internal network communication mechanism.

Pros of Dedicated Proxy Container:

Gerbil and other core Pangolin components maintain better network isolation. The port exposure is limited to a dedicated proxy container.
The proxy container becomes the central point for managing exposed ports. This could simplify port management within the Docker setup.
The proxy container could be implemented using various technologies (e.g., socat, nginx stream, a simple custom proxy).

Cons of Dedicated Proxy Container:

Introducing an additional proxy container adds another component to the architecture and requires extra configuration and management.
Communication between Gerbil and the proxy container introduces some overhead, although this is likely to be minimal for simple proxying scenarios.
While simplifying per-resource port management, the proxy container itself needs to have its port ranges or mechanisms for accepting dynamic port configurations managed somehow, which still requires some initial setup and potentially management of the proxy container's configuration.

@bannert1337 commented on GitHub (Mar 21, 2025): Alternative 3: Dedicated Proxy Container within a Docker Network Keep Gerbil in a standard Docker bridge network or a dedicated network. Introduce a separate, lightweight "proxy" container within the same network. This proxy container would be responsible for exposing the ports to the host. Gerbil would configure this proxy container via an internal network communication mechanism. **Pros of Dedicated Proxy Container:** * Gerbil and other core Pangolin components maintain better network isolation. The port exposure is limited to a dedicated proxy container. * The proxy container becomes the central point for managing exposed ports. This could simplify port management within the Docker setup. * The proxy container could be implemented using various technologies (e.g., `socat`, `nginx stream`, a simple custom proxy). **Cons of Dedicated Proxy Container:** * Introducing an additional proxy container adds another component to the architecture and requires extra configuration and management. * Communication between Gerbil and the proxy container introduces some overhead, although this is likely to be minimal for simple proxying scenarios. * While simplifying per-resource port management, the proxy container itself needs to have its port ranges or mechanisms for accepting dynamic port configurations managed somehow, which still requires some initial setup and potentially management of the proxy container's configuration.

GiteaMirror commented

2026-06-05 04:53:12 -05:00

@bannert1337 commented on GitHub (Mar 21, 2025):

Alternative 4: Docker Socket Communication (Advanced)

Gerbil could potentially interact directly with the Docker daemon (through the Docker socket, or a more secure socket proxy) to request and manage port mappings programmatically.

Pros of Docker Socket Communication:

Allows for fully dynamic and automated port management and container lifecycle management.
Leverages Docker's built-in capabilities for container management.
Using a restricted Docker socket proxy can limit the permissions granted to Gerbil, improving security compared to full Docker socket access.

Cons of Docker Socket Communication:

Implementation is significantly more complex and requires deep understanding of the Docker API and security considerations around Docker socket access.
Directly mounting the raw Docker socket into a container can be a significant security risk if not handled carefully. A socket proxy is strongly recommended for security.
Makes Pangolin very tightly coupled to Docker and potentially less portable.
Requires developers to be proficient in Docker API interaction and security best practices related to container orchestration.

@bannert1337 commented on GitHub (Mar 21, 2025): Alternative 4: Docker Socket Communication (Advanced) Gerbil could potentially interact directly with the Docker daemon (through the Docker socket, or a more secure socket proxy) to request and manage port mappings programmatically. **Pros of Docker Socket Communication:** * Allows for fully dynamic and automated port management and container lifecycle management. * Leverages Docker's built-in capabilities for container management. * Using a restricted Docker socket proxy can limit the permissions granted to Gerbil, improving security compared to full Docker socket access. **Cons of Docker Socket Communication:** * Implementation is significantly more complex and requires deep understanding of the Docker API and security considerations around Docker socket access. * Directly mounting the raw Docker socket into a container can be a significant security risk if not handled carefully. A socket proxy is strongly recommended for security. * Makes Pangolin very tightly coupled to Docker and potentially less portable. * Requires developers to be proficient in Docker API interaction and security best practices related to container orchestration.

GiteaMirror commented

2026-06-05 04:53:14 -05:00

@bannert1337 commented on GitHub (Mar 21, 2025):

Related to #375

@bannert1337 commented on GitHub (Mar 21, 2025): Related to #375

GiteaMirror commented

2026-06-05 04:53:14 -05:00

@strich3 commented on GitHub (Mar 22, 2025):

With that maybe the option of adding port ranges could be very useful!

@strich3 commented on GitHub (Mar 22, 2025): With that maybe the option of adding port ranges could be very useful!

Sign in to join this conversation.

Branches Tags

main

provisioning-resources

api-improvements

crowdin_dev

dev

feat/remember-last-idp-on-smart-login-form

private-resource-enable

refactor/batch-status-requests

dependabot/npm_and_yarn/npm-dependencies-76c57b29af

dependabot/docker/docker-dependencies-6cbd4d48e0

dependabot/go_modules/install/go-install-dependencies-3804ca7238

dependabot/npm_and_yarn/multi-5f1280885e

fix/non-semver-version-error

private-resource-page

dependabot/github_actions/github-actions-dependencies-174564dfd5

resource-launcher

backhaul

exit-node-reconnect

feat/command-palette

ssh

delete-account

msg-delivery

org-only-idp

cicd

patch

site-targets-auto-login

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/pangolin#22710