Resolve "[Alpamon Agent Refactoring] Integrate Main Branch Changes into Refactored Architecture" #163

geunwoonoh · 2025-12-29T08:33:53Z

Summary

Integrates new features from main branch (Tunneling, Auth Manager, Logger refactoring, Ping/Pong) into the refactored architecture.

Changes

Integrate Tunneling feature using Handler pattern (TunnelHandler)
Add Auth Manager / MFA sudo approval workflow
Remove lumberjack from Logger, use systemd journald
Add WebSocket ping/pong heartbeat support

Test plan

go build -v ./... succeeds
go test -v ./... -p 1 all tests pass
Manual testing of Tunnel functionality
Manual testing of Auth Manager sudo approval

Detailed Changes

1. Tunneling Feature (PR #156 Integration)

New files:

pkg/executor/handlers/tunnel/tunnel.go - TunnelHandler implementation
pkg/executor/handlers/tunnel/types.go - Data type definitions
pkg/runner/tunnel_client.go - smux multiplexing tunnel client
pkg/runner/tunnel_worker.go - Tunnel worker subprocess
pkg/runner/tunnel_linux.go - Linux privilege demotion
pkg/runner/tunnel_darwin.go - macOS implementation
pkg/tunnel/conn.go - WebSocket adapter
pkg/tunnel/pool.go - Buffer pool
cmd/alpamon/command/tunnel/tunnel.go - CLI command

Modified files:

pkg/executor/factory.go - Register TunnelHandler
pkg/executor/handlers/common/types.go - Add OpenTunnel, CloseTunnel types
pkg/executor/handlers/common/args.go - Add TargetPort field
internal/protocol/command.go - Add TargetPort mapping
pkg/config/config.go - Add smux configuration

2. Auth Manager / MFA Feature (PR #101 Integration)

New files:

pkg/runner/auth_manager.go - Sudo approval request management (Unix socket)
pkg/runner/control_client.go - Control WebSocket client

Modified files:

cmd/alpamon/command/root.go - ControlClient, AuthManager initialization and shutdown
pkg/runner/pty.go - Add/remove PID mapping for PTY sessions

3. Logger Refactoring (PR #160 Integration)

Modified files:

pkg/logger/logger.go - Remove lumberjack, output to stdout/stderr
cmd/alpamon/command/root.go - Remove lumberjack-related code

4. Ping/Pong Handler (PR #158 Integration)

Modified files:

pkg/runner/client.go - Add SendPongResponse(), handle ping queries

5. Miscellaneous

.github/workflows/release.yml - PackageCloud channel separation
configs/alpamon.service - systemd service configuration update
go.mod, go.sum - Add smux dependency

Architecture Compliance

Compliance with refactoring architecture :

Item	Status	Notes
Handler Pattern	✅	Implemented as TunnelHandler
Factory Pattern	✅	Registered in factory.go
Pool Usage	✅	Commands executed through Pool
Context Propagation	✅	ctx parameter in all handlers
Circular Dependencies	✅	None

Security Considerations

Unix socket permissions 0600 (root only)
Tunnel connections localhost only (127.0.0.1)
Authentication header ID/Key based
TLS configuration option available

Concurrency Safety

Component	Protection Method
AuthManager	sync.RWMutex
ControlClient	sync.Mutex
activeTunnels	sync.RWMutex
terminals	sync.RWMutex

Related Issues/PRs

Closes [Alpamon Agent Refactoring] Integrate Main Branch Changes into Refactored Architecture #162
Integrates PR feat: Support for Websh based TCP-tunneling #156 (Tunneling)
Integrates PR feat: implement MFA-based sudo approval system #101 (Auth Manager)
Integrates PR refactor(logger): remove lumberjack, use systemd journald for logging #160 (Logger refactoring)
Integrates PR feat(runner): add ping/pong handler for WebSocket heartbeat #158 (Ping/Pong)

Co-authored-by: Copilot <[email protected]>

….Close() calls

…nation

Co-authored-by: Copilot <[email protected]>

…nt-via-mfa-authentication' of https://github.com/alpacax/alpamon into 99-sudo-privilege-verification-and-centralized-management-via-mfa-authentication

…tion-and-centralized-management-via-mfa-authentication

- Add alpamon-pam as recommended dependency in .goreleaser.yaml - Debian/Ubuntu: recommends alpamon-pam - CentOS/RHEL: recommends alpamon-pam - Update README.md with PAM module documentation - Add installation instructions with/without PAM module - Document PAM configuration steps for /etc/pam.d/sudo and /etc/sudo.conf - Add note about Alpamon service requirement for PAM authentication

…tion-and-centralized-management-via-mfa-authentication

Convert Korean comment in Dockerfile to English for better maintainability. Changes: - Dockerfiles/ubuntu/22.04/Dockerfile: Convert GOARCH architecture comment

Add AuthManager for centralized sudo privilege verification: - Unix domain socket server (/var/run/alpamon/auth.sock) - Handle check_user requests from pam_alpamon.so - Handle sudo_approval requests from alpacon_approval.so - Distinguish Alpacon users (pidToSessionMap) vs local users (localSudoRequests) - Retry logic with exponential backoff for WebSocket communication - Response routing back to PAM/sudo plugin via Unix socket Security improvements: - Root-only socket permissions (0600) - 30-second timeout to prevent DoS - Request ID based mapping for concurrent requests - Proper cleanup on timeout and connection errors Integration: - WebSocket communication with alpacon-server - Coordinate with PtyClient session management - Support both authenticated and local user approval flows

…atting Replace Msg(fmt.Sprintf(...)) with Msgf(...) to fix staticcheck SA1006 linting error. This resolves the golangci-lint failure in CI while maintaining the same functionality.

Use Str() instead of Err(fmt.Errorf()) to fix staticcheck SA1006 error. The result variable is already a string, so we use structured logging with Str().

- Fix critical mutex double unlock bug in HandleSudoApprovalResponse - Previously unlocked mutex inside loop, causing panic on second unlock - Now unlocks once after checking both alpacon and local requests - Improve connection lifecycle management in handleSudoRequest - Remove defer close() to prevent double-close with manual cleanup - Explicitly close connections after check_user requests - Document that sudo_approval connections are managed by response handlers - Add default case for unknown request types with proper cleanup - Improve timeout handling with explicit service shutdown cleanup

- Rename is_alpcon_user to is_alpacon_user for consistency - SudoApprovalRequest, SudoApprovalResponse structs - MFAResponse, IsAlpconResponse structs

Signed-off-by: sangyeong01 <[email protected]>

…tion-and-centralized-management-via-mfa-authentication

- Remove hardcoded sudo group addition in adduser - Sudo privilege is now controlled by alpacon-server via gids

- Add ControlClient to handle control WebSocket connection - Refactor client.go to separate control logic into control_client.go - Support sudo_approval request/response via control channel

…response)

…ufReader

- Rename variables to camelCase (unix_conn -> unixConn, sudo_approval_req -> sudoApprovalReq) - Add BaseRequest struct for type-safe request parsing - Extract createSendOperation method from sendSudoRequestWithRetry - Add completion channels for proper timeout handling - Close connection after sendSudoApprovalResponse in cleanupTimeoutRequest - Call RemovePIDSessionMapping when PtyClient disconnects

- Remove lumberjack dependency for log rotation - Output logs to stderr for systemd/journald to capture - Update systemd service to use journald (StandardOutput/Error=journal) - Add log viewing instructions to README

…tion-and-centralized-management-via-mfa-authentication

…nd-centralized-management-via-mfa-authentication feat: implement MFA-based sudo approval system

…rjack-use-stdout

…tdout refactor(logger): remove lumberjack, use systemd journald for logging

feat: Support for Websh based TCP-tunneling

Add support for deploying packages to different PackageCloud repositories based on release tag patterns: - stable (alpamon): vX.Y.Z tags - latest (alpamon-latest): vX.Y.Z-rc.N tags - dev (alpamon-dev): vX.Y.Z-dev, -beta.N, -alpha.N tags Also enable automatic GitHub pre-release detection in goreleaser.

…loud-channels-stable-dev-latest

…ls-stable-dev-latest Resolve "Separate PackageCloud Channels (stable, dev, latest)"

…actoring-integrate-main-branch-changes-into-refactored-architecture

Add TunnelHandler to handle the following commands: opentunnel, closetunnel Define types and structs related to TunnelHandler.

Add fields related to tunneling functionality in conjunction with TunnelHandler.

…ation Update RegisterAll() to include TunnelHandler registration.

hyunwoo hwang and others added 30 commits August 5, 2025 14:40

add auth manager and related changes

2af27c6

add test code and fix authmanager

a6e2e7e

Update cmd/alpamon/command/root.go

b44eff0

Co-authored-by: Copilot <[email protected]>

Update pkg/runner/auth_manager.go

8c8ea5f

Co-authored-by: Copilot <[email protected]>

Fix connection leak in handleSudoRequest by adding explicit unix_conn…

2d22993

….Close() calls

Fix golangci-lint issues: handle error return values and unused fields

2842fd2

Fix staticcheck SA1006 by using fmt.Sprintf instead of string concate…

1a36799

…nation

modify socket path directory management

82b8b33

add local fall back and alpacon_approval.c

5589152

fix mistake

c12ee1a

Update pkg/runner/pty.go

1ba9fd6

Co-authored-by: Copilot <[email protected]>

Update pkg/runner/auth_manager.go

8419b0e

Co-authored-by: Copilot <[email protected]>

update build

8c89095

Merge branch '99-sudo-privilege-verification-and-centralized-manageme…

36d51ae

…nt-via-mfa-authentication' of https://github.com/alpacax/alpamon into 99-sudo-privilege-verification-and-centralized-management-via-mfa-authentication

Merge remote-tracking branch 'origin' into 99-sudo-privilege-verifica…

0ea7abb

…tion-and-centralized-management-via-mfa-authentication

Merge remote-tracking branch 'origin' into 99-sudo-privilege-verifica…

779bf92

…tion-and-centralized-management-via-mfa-authentication

refactor: convert Korean comments to English

ab7a614

Convert Korean comment in Dockerfile to English for better maintainability. Changes: - Dockerfiles/ubuntu/22.04/Dockerfile: Convert GOARCH architecture comment

fix(runner): use Msgf instead of Msg with fmt.Sprintf for proper form…

d92a672

…atting Replace Msg(fmt.Sprintf(...)) with Msgf(...) to fix staticcheck SA1006 linting error. This resolves the golangci-lint failure in CI while maintaining the same functionality.

fix(runner): replace Err with Str for string error logging

79aeaad

Use Str() instead of Err(fmt.Errorf()) to fix staticcheck SA1006 error. The result variable is already a string, so we use structured logging with Str().

refactor: standardize is_alpacon_user field naming in auth structs

4a43682

- Rename is_alpcon_user to is_alpacon_user for consistency - SudoApprovalRequest, SudoApprovalResponse structs - MFAResponse, IsAlpconResponse structs

fix: set releasing packages action on matrix

732c331

Signed-off-by: sangyeong01 <[email protected]>

Merge remote-tracking branch 'origin' into 99-sudo-privilege-verifica…

8d7dc9b

…tion-and-centralized-management-via-mfa-authentication

refactor(runner): remove unconditional sudo group addition

828d370

- Remove hardcoded sudo group addition in adduser - Sudo privilege is now controlled by alpacon-server via gids

feat(runner): add ControlClient for server control channel

b2a1fae

- Add ControlClient to handle control WebSocket connection - Refactor client.go to separate control logic into control_client.go - Support sudo_approval request/response via control channel

fix: correct typo in response type (is_alpcon_response -> is_alpacon_…

90ab531

…response)

fix(package): change alpamon-pam dependency from recommends to suggests

25203cb

Add smux dependancy

3b7fe86

jisung-02 and others added 25 commits December 22, 2025 17:25

Define constants for readability and place type definitions at the top

0889a1a

Move constant definitions to the top to improve readability

94d914f

Fix to prevent CPU spin in tunnel stream handler

3d4494e

Fix to prevent data loss by ensuring all buffered data is read from b…

d933cdf

…ufReader

Suppress redundant error logs when killing finished processes

f6581a3

Protect WebSocket writes with mutex for concurrent stream safety

146ebf0

Synchronize tunnel deletion to prevent race condition in cleanup

0291e0f

Add port validation and fix potential issues in tunnel client

63c7c31

Merge branch 'main' into 145-tunneling

15c253e

refactor(logger): remove lumberjack, use systemd journald for logging

845377a

- Remove lumberjack dependency for log rotation - Output logs to stderr for systemd/journald to capture - Update systemd service to use journald (StandardOutput/Error=journal) - Add log viewing instructions to README

Suppress CodeQL SSRF warning for trusted tunnel URL

cad3df2

Merge remote-tracking branch 'origin' into 99-sudo-privilege-verifica…

ea20dfe

…tion-and-centralized-management-via-mfa-authentication

Merge pull request #101 from alpacax/99-sudo-privilege-verification-a…

66268e2

…nd-centralized-management-via-mfa-authentication feat: implement MFA-based sudo approval system

Reorder const and var declarations to follow Go conventions

dbcb7b0

Merge remote-tracking branch 'origin/main' into refactor/remove-lumbe…

50687ca

…rjack-use-stdout

Merge pull request #160 from alpacax/refactor/remove-lumberjack-use-s…

e750b93

…tdout refactor(logger): remove lumberjack, use systemd journald for logging

Merge pull request #156 from alpacax/145-tunneling

ab2f56d

feat: Support for Websh based TCP-tunneling

Merge remote-tracking branch 'origin/main' into 157-separate-packagec…

058842d

…loud-channels-stable-dev-latest

Merge pull request #161 from alpacax/157-separate-packagecloud-channe…

1fa8107

…ls-stable-dev-latest Resolve "Separate PackageCloud Channels (stable, dev, latest)"

Merge remote-tracking branch 'origin/main' into 162-alpamon-agent-ref…

cd8ada4

…actoring-integrate-main-branch-changes-into-refactored-architecture

feat(handlers): implement TunnelHandler

ea4d9be

Add TunnelHandler to handle the following commands: opentunnel, closetunnel Define types and structs related to TunnelHandler.

feat(protocol): add tunnel specific field

469b2ca

Add fields related to tunneling functionality in conjunction with TunnelHandler.

feat(executor): update RegisterAll() to include TunnelHandler registr…

0052267

…ation Update RegisterAll() to include TunnelHandler registration.

geunwoonoh requested review from jisung-02 and junho226 December 29, 2025 08:33

geunwoonoh self-assigned this Dec 29, 2025

geunwoonoh merged commit 4cf6ff7 into 131-alpamon-agent-refactoring Dec 29, 2025
2 checks passed

geunwoonoh deleted the 162-alpamon-agent-refactoring-integrate-main-branch-changes-into-refactored-architecture branch December 29, 2025 08:37

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Resolve "[Alpamon Agent Refactoring] Integrate Main Branch Changes into Refactored Architecture" #163

Resolve "[Alpamon Agent Refactoring] Integrate Main Branch Changes into Refactored Architecture" #163

Uh oh!

geunwoonoh commented Dec 29, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

Resolve "[Alpamon Agent Refactoring] Integrate Main Branch Changes into Refactored Architecture" #163

Resolve "[Alpamon Agent Refactoring] Integrate Main Branch Changes into Refactored Architecture" #163

Uh oh!

Conversation

geunwoonoh commented Dec 29, 2025

Summary

Changes

Test plan

Detailed Changes

1. Tunneling Feature (PR #156 Integration)

2. Auth Manager / MFA Feature (PR #101 Integration)

3. Logger Refactoring (PR #160 Integration)

4. Ping/Pong Handler (PR #158 Integration)

5. Miscellaneous

Architecture Compliance

Security Considerations

Concurrency Safety

Related Issues/PRs

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants