{"id":35197090,"url":"https://github.com/alpacax/alpamon","last_synced_at":"2026-02-26T10:54:47.681Z","repository":{"id":258168252,"uuid":"863384392","full_name":"alpacax/alpamon","owner":"alpacax","description":"System agent for Alpacon to enable secure remote access and monitoring.","archived":false,"fork":false,"pushed_at":"2026-01-19T04:55:23.000Z","size":1195,"stargazers_count":12,"open_issues_count":5,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-01-19T13:41:33.341Z","etag":null,"topics":["agent","alpacon","go","golang","pty","websocket"],"latest_commit_sha":null,"homepage":"https://www.alpacax.com/alpacon","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alpacax.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-09-26T07:51:21.000Z","updated_at":"2026-01-16T02:41:55.000Z","dependencies_parsed_at":"2024-10-28T05:35:09.664Z","dependency_job_id":"d0cbe71e-2340-492c-8b3f-ca53633a0c60","html_url":"https://github.com/alpacax/alpamon","commit_stats":null,"previous_names":["alpacanetworks/alpamon-go","alpacax/alpamon"],"tags_count":79,"template":false,"template_full_name":null,"purl":"pkg:github/alpacax/alpamon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alpacax%2Falpamon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alpacax%2Falpamon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alpacax%2Falpamon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alpacax%2Falpamon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alpacax","download_url":"https://codeload.github.com/alpacax/alpamon/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alpacax%2Falpamon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28805489,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-27T05:43:52.625Z","status":"ssl_error","status_checked_at":"2026-01-27T05:43:48.957Z","response_time":168,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","alpacon","go","golang","pty","websocket"],"created_at":"2025-12-29T07:59:38.110Z","updated_at":"2026-01-27T06:11:57.804Z","avatar_url":"https://github.com/alpacax.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Alpamon\nNew Go-based Secure Server Agent for Alpacon\n\n**Alpamon** is a server agent for **Alpacon**. Each server should have Alpamon installed to be controlled via Alpacon.\n\nThis guide outlines the step-by-step process for installing Alpamon within a development environment. The installation requires an active Internet connection or the appropriate configuration of a proxy server.\n\n## System Requirements\n\nTo run Alpamon, ensure your system meets the following requirements:\n- Operating system: Linux, macOS, or Windows (via WSL)\n- Go version: 1.24.4 or higher\n- Memory: At least 512MB RAM\n- Disk space: At least 100MB free space\n\n## Getting started\nTo build Alpamon, ensure you have:\n- [Go](https://go.dev/doc/install) version 1.24.4 or higher installed(required for building).\n  - The module is compatible with Go **1.23** and above for usage (importing and running pre-built binaries).\n  - Make sure `$GOPATH` is set and `$GOPATH/bin` is added to your system’s `PATH`.\n  \n## Installation\nDownload the latest `alpamon` directly from our releases page or install it using package managers on Linux.\n\n### Linux\n\n#### Debian and Ubuntu\n```bash\ncurl -s https://packagecloud.io/install/repositories/alpacax/alpamon/script.deb.sh?any=true | sudo bash\n\n# Install alpamon (includes PAM module by default)\nsudo apt-get install alpamon\n\n# Install without PAM module\nsudo apt-get install alpamon --no-install-recommends\n```\n\n#### CentOS and RHEL\n```bash\ncurl -s https://packagecloud.io/install/repositories/alpacax/alpamon/script.rpm.sh?any=true | sudo bash\n\n# Install alpamon (includes PAM module by default)\nsudo yum install alpamon\n\n# Install without PAM module\nsudo yum install alpamon --setopt=install_weak_deps=False\n```\n\n### PAM Module\n\nBy default, `alpamon` installation includes the `alpamon-pam` package, which provides PAM (Pluggable Authentication Modules) integration for advanced authentication features:\n- **pam_alpamon.so**: Verifies Alpacon users during sudo authentication\n- **alpacon_approval.so**: Handles sudo command approval requests\n\n#### Configuration\nAfter installation, configure PAM and sudo to enable the authentication features:\n\n1. Add to `/etc/pam.d/sudo`:\n```\nauth [user_unknown=ignore auth_err=die success=done default=bad] pam_alpamon.so\n```\n\n2. Add to `/etc/sudo.conf`:\n```\nPlugin approval_plugin alpacon_approval.so\n```\n\n**Note**: The Alpamon service must be running with socket at `/var/run/alpamon/auth.sock` for PAM authentication to work.\n\n### macOS\n\n#### Clone the source code\nTo get started on macOS, clone the source code from the repository:\n```bash\ngit clone https://github.com/alpacax/alpamon.git\n```\n\n#### Generate Ent Schema Code with Entgo\nTo generate Ent schema code with custom features, navigate to the root of the project and use the following command:\n```bash\ngo run -mod=mod entgo.io/ent/cmd/ent@v0.14.2 generate --feature sql/modifier --target ./pkg/db/ent ./pkg/db/schema\n```\n\n#### Install Atlas CLI (Development Only)\nAtlas CLI is **only required for development** when you need to generate new migration files after modifying database schemas in `pkg/db/schema/`. Production deployments do not require Atlas CLI as migrations are executed directly from embedded SQL files.\n\nTo install Atlas CLI for development:\n```bash\ncurl -sSf https://atlasgo.sh | sh\n```\n\nAfter modifying Ent schemas, generate migration files:\n```bash\natlas migrate diff \u003cmigration_name\u003e \\\n  --dir \"file://pkg/db/migration\" \\\n  --to \"ent://pkg/db/ent/schema\" \\\n  --dev-url \"sqlite://alpamon.db?mode=memory\"\n```\n\n#### Install Go dependencies\nMake sure you have Go installed. Then, navigate to the project root and download the necessary Go packages:\n```bash\ngo mod tidy\n```\n\n## Configure\n\nAlpamon can be configured via the files listed below.\n\n- `/etc/alpamon/alpamon.conf`\n- `~/.alpamon.conf`\n\nIt is recommended to use `/etc/alpamon/alpamon.conf` for deployment, but you can use `~/.alpamon.conf` for development.\n\n```ini\n[server]\nurl = http://localhost:8000\nid = \nkey = \n\n[ssl]\nverify = true\nca_cert = \n\n[logging]\ndebug = true\n```\n\n### Configuration details\n\n- `server`: Server settings\n    - `url`: The URL for Alpaca Console. If you are in a local development environment, this will be `https://localhost:8000`.\n    - `id`: Server ID\n    - `key`: Server Key\n    - `ca_cert`: Path for the CA certificate\n- `logging`: Logging settings\n    - `debug`: Whether to print debug logs or not\n \nFor testing with the `Alpacon-Server`, you can use the following values:\n- `url` = `http://localhost:8000`\n- `id` = `7a50ea6c-2138-4d3f-9633-e50694c847c4`\n- `key` = `alpaca`\n\n\n## Run\n\n### Local build\n\nTo build Alpamon as a binary for local development, run the following command from the project root:\n```sh\ngo build -o alpamon ./cmd/alpamon\n```\nThis will create an `alpamon` executable in your project root. You can run it directly:\n\n```sh\n./alpamon\n```\n\n### Local environment\n\nTo run Alpamon in a local development environment, you can also use Go directly:\n```sh\ngo run ./cmd/alpamon\n```\n\n### Docker\nYou can also use docker to test alpamon in various Linux distributions. We use Docker Desktop to test alpamon on following distributions.\n\n- Ubuntu: 18.04, 20.04, 22.04\n- Debian: 10, 11\n- RedHat: 8, 9\n- CentOS: 7\n\n#### Build\nBuild docker images with the build script.\n```\n./Dockerfiles/build.sh\n```\n\n#### Run\nYou can run containers for these images in Docker Desktop or using command line like below.\n```\ndocker run alpamon:ubuntu-22.04\n```\n- Note: This will run the container with the default workspace URL (http://localhost:8000), plugin ID, and key values. \nFor more details, refer to the `entrypoint.sh` file in the Dockerfiles directory corresponding to each operating system.\n\nTo run the container with a custom workspace URL, plugin ID, and key, use the following command:\n```\ndocker run \\\n  -e ALPACON_URL=\"your_workspace_url\" \\\n  -e PLUGIN_ID=\"your_plugin_id\" \\\n  -e PLUGIN_KEY=\"your_plugin_key\" \\\n  alpamon:latest\n```\n- Replace the environment variable values (your_workspace_url, your_plugin_id, your_plugin_key) with your actual workspace configuration.\n\n### Deploy as a service\n\nFor Linux systems supporting `systemd`, you can run `alpamon` as a systemd service. In this case, you need to adapt `alpamon/config/alpamon.service` for your environment.\n\nSpecifically, `ExecStart` should be something like `/usr/local/bin/alpamon`.\n\nRun the following commands to prepare system directories.\n\n```sh\nsudo cp alpamon/config/tmpfile.conf /usr/lib/tmpfiles.d/alpamon.conf\nsudo systemd-tmpfiles --create\n```\n\nRun the following commands to install a systemd service.\n\n```sh\nsudo cp alpamon/config/alpamon.service /lib/systemd/system/alpamon.service\nsudo systemctl daemon-reload\nsudo systemctl start alpamon.service\nsudo systemctl enable alpamon.service\nsystemctl status alpamon.service\n```\n\nThe result would look like the following. The status must be loaded and active (running).\n\n```\nalpamon.service - alpamon agent for Alpacon\n     Loaded: loaded (/lib/systemd/system/alpamon.service; enabled; vendor preset: enabled)\n     Active: active (running) since Thu 2023-09-28 23:48:55 KST; 4 days ago\n```\n\n### Logs\n\nAlpamon logs are managed by systemd's journald. Use the following commands to view logs:\n\n```bash\n# View all logs\njournalctl -u alpamon\n\n# Follow logs in real-time\njournalctl -u alpamon -f\n\n# View logs since today\njournalctl -u alpamon --since today\n\n# View recent logs (last 100 lines)\njournalctl -u alpamon -n 100\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falpacax%2Falpamon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falpacax%2Falpamon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falpacax%2Falpamon/lists"}