{"id":18088997,"url":"https://github.com/eriksjolund/socket-activate-echo","last_synced_at":"2025-07-17T14:04:48.665Z","repository":{"id":41893385,"uuid":"477283405","full_name":"eriksjolund/socket-activate-echo","owner":"eriksjolund","description":"socket activated echo server","archived":false,"fork":false,"pushed_at":"2025-03-23T08:22:09.000Z","size":32,"stargazers_count":6,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-13T04:36:39.742Z","etag":null,"topics":["container","demo","echo-server","podman","socket-activation","systemd-service"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eriksjolund.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","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}},"created_at":"2022-04-03T08:40:43.000Z","updated_at":"2025-03-23T08:17:27.000Z","dependencies_parsed_at":"2024-10-31T17:42:38.845Z","dependency_job_id":"e253e578-176e-4a73-a244-242e7b2011e9","html_url":"https://github.com/eriksjolund/socket-activate-echo","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/eriksjolund/socket-activate-echo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eriksjolund%2Fsocket-activate-echo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eriksjolund%2Fsocket-activate-echo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eriksjolund%2Fsocket-activate-echo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eriksjolund%2Fsocket-activate-echo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eriksjolund","download_url":"https://codeload.github.com/eriksjolund/socket-activate-echo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eriksjolund%2Fsocket-activate-echo/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265614095,"owners_count":23798384,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["container","demo","echo-server","podman","socket-activation","systemd-service"],"created_at":"2024-10-31T17:42:33.691Z","updated_at":"2025-07-17T14:04:48.645Z","avatar_url":"https://github.com/eriksjolund.png","language":"C++","readme":"# socket-activate-echo\n\nAn echo server that supports systemd socket activation\n\nfamily   | type        | support\n-------  | ----        | -------\nAF_UNIX  | SOCK_STREAM | yes\nAF_INET  | SOCK_STREAM | yes\nAF_INET6 | SOCK_STREAM | yes\nAF_VSOCK | SOCK_STREAM | yes\nAF_UNIX  | SOCK_DGRAM  | yes (but no support for outgoing traffic when run in container because the client socket path on the host is not accessible from within the container) \nAF_INET  | SOCK_DGRAM  | yes\nAF_INET6 | SOCK_DGRAM  | yes\n\n### Requirements\n\n* __podman__  version 3.4.0 (released September 2021) or newer\n* __container-selinux__ version 2.183.0 (released April 2022) or newer\n\nIf you are using an older version of __container-selinux__ and it does not work, add `--security-opt label=disable` to `podman run`.\n\n### Installation\n\n1. Install __socat__\n    ```\n    sudo dnf -y install socat\n    ```\n\n### About the container image\n\nThe container image [__ghcr.io/eriksjolund/socket-activate-echo__](https://github.com/eriksjolund/socket-activate-echo/pkgs/container/socket-activate-echo)\nis built by the GitHub Actions workflow [.github/workflows/publish_container_image.yml](.github/workflows/publish_container_image.yml)\nfrom the file [./Containerfile](./Containerfile).\n\n### Activate an instance of a templated systemd user service\n\n1. Start the echo server sockets\n    ```\n    git clone https://github.com/eriksjolund/socket-activate-echo.git\n    mkdir -p ~/.config/systemd/user\n    cp -r socket-activate-echo/systemd/* ~/.config/systemd/user\n    systemctl --user daemon-reload\n    systemctl --user start echo@demo.socket\n    ```\n\n2. Run the commands\n    ```\n    $ echo hello | socat - tcp4:127.0.0.1:3000\n    hello\n    $ echo hello | socat - tcp6:[::1]:3000\n    hello\n    $ echo hello | socat - udp4:127.0.0.1:3000\n    hello\n    $ echo hello | socat - udp6:[::1]:3000\n    hello\n    $ echo hello | socat - unix:$HOME/echo_stream_sock.demo\n    hello\n    $ echo hello | socat - VSOCK-CONNECT:1:3000\n    hello\n    ```\n\n3. Try establishing an outgoing connection\n    ```\n    $ podman exec -t echo-demo curl https://podman.io\n    curl: (6) Could not resolve host: podman.io\n    $\n    ```\n    (The command-line option `--network=none` was added to prevent the container from establishing outgoing connections)\n\n### Socket activate SOCK_STREAM sockets with systemd-socket-activate\n\n1. Socket activate the echo server\n    ```\n    systemd-socket-activate -l /tmp/stream.sock \\\n        -l 4000 -l vsock:4294967295:4000 podman run --rm --name echo2 \\\n        --network=none ghcr.io/eriksjolund/socket-activate-echo\n    ```\n    Instead of _VMADDR_CID_ANY_ (4294967295) we could also have used _VMADDR_CID_LOCAL_ (1), in other words,\n    `-l vsock:1:4000` (see [`man 7 vsock`](https://man7.org/linux/man-pages/man7/vsock.7.html)).\n\n2. In another shell\n    ```\n    $ echo hello | socat - unix:/tmp/stream.sock\n    hello\n    $ echo hello | socat - tcp4:127.0.0.1:4000\n    hello\n    $ echo hello | socat - tcp6:[::1]:4000\n    hello\n    $ echo hello | socat - VSOCK-CONNECT:1:4000\n    hello\n    ```\n\n3. Try establishing an outgoing connection\n    ```\n    $ podman exec -t echo2 curl https://podman.io\n    curl: (6) Could not resolve host: podman.io\n    $\n    ```\n\n### Socket activate SOCK_DGRAM sockets with systemd-socket-activate\n\n1. Socket activate the echo server\n    ```\n    systemd-socket-activate --datagram \\\n        -l 5000 podman run --rm --name echo3 \\\n        --network=none ghcr.io/eriksjolund/socket-activate-echo\n    ```\n\n2. In another shell\n    ```\n    $ echo hello | socat - udp4:127.0.0.1:5000\n    hello\n    $ echo hello | socat - udp6:[::1]:5000\n    hello\n    ```\n\n3. Try establishing an outgoing connection\n    ```\n    $ podman exec -t echo3 curl https://podman.io\n    curl: (6) Could not resolve host: podman.io\n    $\n    ```\n\n### Run the echo container inside a VM and connect over AF_VSOCK (SOCK_STREAM)\n\n1. Install requirements\n\n    ```\n    sudo dnf install -y qemu butane coreos-installer\n    ```\n\n2.  Start the Fedora CoreOS VM by running these commands on the host\n\n    ```\n    STREAM=next\n    CID=20\n    mkdir -p ~/.local/share/libvirt/images/\n    file=$(coreos-installer download -s \"${STREAM}\" -p qemu -f qcow2.xz --decompress -C ~/.local/share/libvirt/images/)\n    cat vm/echo.butane | butane --strict --pretty --files-dir systemd \u003e file.ign\n    qemu-kvm -m 2048 \\\n      -device \"vhost-vsock-pci,id=vhost-vsock-pci0,guest-cid=$CID\" \\\n      -cpu host -nographic -snapshot \\\n      -drive \"if=virtio,file=$file\" \\\n      -fw_cfg name=opt/com.coreos/config,file=file.ign -nic \"user,model=virtio\"\n    ```\n\n    The Context Identifier (CID) is an arbitrary number that is used to identify the VM (see `man vsock`).\n\n3.  Run on the host\n    ```\n     $ CID=20\n     $ echo hello | socat -t 30 - VSOCK-CONNECT:$CID:3000\n     hello\n    ```\n\n### Troubleshooting\n\n#### The container takes long time to start\n\nPulling a container image may take long time. This delay can be avoided by pulling the container\nimage beforehand and adding the command-line option `--pull=never` to `podman run`.\n\n#### socat times out before receiving the reply\n\nIf __socat__ does not receive any reply within a certain time limit it terminates before getting the reply. The timeout is __0.5 seconds__ by default.\nSymptoms of this could be\n\n```\n$ systemctl --user start echo@demo.socket\n$ echo hello | socat - udp4:127.0.0.1:3000\n$ echo hello | socat - udp4:127.0.0.1:3000\nhello\n```\n\nTo configure the timeout to be 30 seconds, add the command-line option `-t 30`.\n\n```\n$ echo hello | socat -t 30 - udp4:127.0.0.1:3000\nhello\n```\n\nAnother way to handle the problem is to use the command-line option __readline__ to get an interactive user interface. Type the word _hello_  and see it being echoed back. \n\n```\n$ socat readline udp4:127.0.0.1:3000\nhello\nhello\n```\n\nIn this case there will be no timeout because none of the channels have reached EOF.\n\nA good way to diagnose problems is to look in the journald log for the service:\n\n```\njournalctl -xe --user -u echo@demo.service\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feriksjolund%2Fsocket-activate-echo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feriksjolund%2Fsocket-activate-echo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feriksjolund%2Fsocket-activate-echo/lists"}