{"id":19637854,"url":"https://github.com/n-r-w/shadow-client","last_synced_at":"2025-04-28T16:26:54.499Z","repository":{"id":193772973,"uuid":"688663799","full_name":"n-r-w/shadow-client","owner":"n-r-w","description":"Cloak + WireGuard + Docker + LAN gateway/proxy (client-side)","archived":false,"fork":false,"pushed_at":"2023-12-31T22:46:49.000Z","size":23,"stargazers_count":13,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-30T11:21:56.765Z","etag":null,"topics":["cloak","docker","gateway","wireguard"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/n-r-w.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2023-09-07T20:44:59.000Z","updated_at":"2025-03-24T19:07:20.000Z","dependencies_parsed_at":"2023-09-09T23:23:06.468Z","dependency_job_id":"87776b81-963f-4a77-947f-8a4d247f69d4","html_url":"https://github.com/n-r-w/shadow-client","commit_stats":null,"previous_names":["n-r-w/shadow-client"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n-r-w%2Fshadow-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n-r-w%2Fshadow-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n-r-w%2Fshadow-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n-r-w%2Fshadow-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/n-r-w","download_url":"https://codeload.github.com/n-r-w/shadow-client/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251344552,"owners_count":21574562,"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":["cloak","docker","gateway","wireguard"],"created_at":"2024-11-11T12:36:30.774Z","updated_at":"2025-04-28T16:26:54.466Z","avatar_url":"https://github.com/n-r-w.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cloak + WireGuard + Docker  + LAN gateway (client-side)\n\n## Client-side setup for internet access through a separate gateway in the local network. Server-side here \u003chttps://github.com/n-r-w/shadow-server\u003e\n\n### The first step is to install the server-side component because during its installation, encryption keys are generated, which will be needed here.\n\nData flows through the following chain:\n\n- Computer (LAN) with the client part of this configuration specified as gateway or proxy server\n- Gateway (LAN)\n- WireGuard client (LAN)\n- Cloak client (LAN)\n- Censored Internet\n- Cloak server (remote)\n- WireGuard server (remote)\n- Free Internet\n\nFor simplicity, all operations are performed as root, using Ubuntu 22.04 as an example. All settings are for IPv4 only.\n\n## Go to the home folder\n\n```bash\ncd /root\n```\n\n## docker setup\n\n### Install docker Manually\n\nInstall docker manually using manual at \u003chttps://docs.docker.com/engine/install/ubuntu/\u003e + install docker-compose:\n\n```bash\napt update \u0026\u0026 apt install -y ca-certificates curl gnupg \u0026\u0026 \\\ninstall -m 0755 -d /etc/apt/keyrings \u0026\u0026 \\\ncurl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg --yes \u0026\u0026 \\\nchmod a+r /etc/apt/keyrings/docker.gpg \u0026\u0026 \\\nif [ ! -e /etc/apt/sources.list.d/docker.list ]; then\necho \\\n\"deb [arch=\"$(dpkg --print-architecture)\" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \\\n\"$(. /etc/os-release \u0026\u0026 echo \"$VERSION_CODENAME\")\" stable\" | \\\nsudo tee /etc/apt/sources.list.d/docker.list \u003e /dev/null\nfi \u0026\u0026 \\\napt update \u0026\u0026 \\\napt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin \u0026\u0026 \\\nwget https://github.com/docker/compose/releases/download/v2.21.0/docker-compose-linux-x86_64 \u0026\u0026 \\\nmv docker-compose-linux-x86_64 /usr/local/bin/docker-compose \u0026\u0026 \\\nchmod +x /usr/local/bin/docker-compose\n```\n\n### Alternatively, install docker via snap (in Ubuntu 22.04, it is not working at the moment)\n\n```bash\napt install -y snapd \u0026\u0026 snap install docker\n```\n\n## Setup\n\n### Download this repository\n\n```bash\ngit clone https://github.com/n-r-w/shadow-client.git \u0026\u0026 cd shadow-client\n```\n\n### Set up environment variables for docker\n\nIn the doc directory there is an example file with environment variables ```env.txt```. Copy it to the ```.env``` file, which contains environment variables for ```docker-compose```\n\n```bash\napt install -y nano \u0026\u0026 \\\ncp ./doc/env.txt ./.env \u0026\u0026 \\\nnano ./.env\n```\n\nSetting the values ​​of the variables\n\n- ```REMOTE_IP``` ip address of \u003chttps://github.com/n-r-w/shadow-server\u003e\n- ```PARENT_INTERFACE``` default interface on host\n- ```SUBNET``` LAN subnet\n- ```LAN_GATEWAY``` LAN gateway\n- ```VPN_GATEWAY``` gateway for lan clients to access vpn. must be in LAN subnet and not used by any other LAN device. It's ip of wireguard server\n- ```CK_IP``` ip address of cloak server. must be in LAN subnet and not used by any other LAN device\n\nEncryption keys that were generated earlier during the server installation process:\n\n- ```WG_CLIENT_PRIVATE_KEY``` wireguard client private key\n- ```WG_SERVER_PUBLIC_KEY``` wireguard server public key\n- ```CK_UID```cloak client UID\n- ```CK_PUBLIC_KEY``` cloak server public key\n\nIf it is necessary to exclude certain domains from the VPN:\n\n- Specify their names in the ```WG_EXCLUDED_DOMAINS``` variable\n- If necessary, specify the IP in the ```WG_EXCLUDED_IPS``` variable\n\nRules for exclusions are generated at startup, so after changing ```WG_EXCLUDED_DOMAINS```/```WG_EXCLUDED_IPS```, it is necessary to reboot the operating system (better) or restart the wireguard container.\n\nIf you want to use a proxy server, specify variables:\n\n- ```PROXY_SOCKS_PORT``` danted server will be launched on this port\n- ```PROXY_HTTP_PORT``` tinyproxy server will be launched on this port\n\nDespite the presence of the cloak keepalive option, the connection to the cloak server may be interrupted due to inactivity and then not restored. To solve this problem, you can use the following environment variables. Ping will be performed in a random range from MIN_PING_DELAY to MAX_PING_DELAY seconds.\n\n- ```PING_HOST``` host to ping\n- ```MIN_PING_DELAY``` minimum ping delay\n- ```MAX_PING_DELAY``` maximum ping delay\n\n## Test run\n\nWe check that everything starts (the first launch is long)\n\n```bash\ndocker-compose up\n```\n\nPress CTRL+C and then\n\n```bash\ndocker-compose down\n```\n\n## Create systemd service to automatically launch a container\n\nIf installed via ```snap```:\n\n```bash\ncp ./doc/shadow-client-snap.service /etc/systemd/system/shadow-client-snap.service \u0026\u0026 \\\nsystemctl daemon-reload \u0026\u0026 \\\nsystemctl enable shadow-client-snap \u0026\u0026 \\\nsystemctl start shadow-client-snap\n```\n\nIf you installed it according to the instructions from the ubuntu website:\n\n```bash\ncp ./doc/shadow-client.service /etc/systemd/system/shadow-client.service \u0026\u0026 \\\nsystemctl daemon-reload \u0026\u0026 \\\nsystemctl enable shadow-client \u0026\u0026 \\\nsystemctl start shadow-client\n```\n\n## Configuring devices in the local network to connect to the VPN\n\nIn case to use this configuration as a gateway:\n\n- Set the IP address specified in the ```VPN_GATEWAY``` variable as the gateway\n- In the network interface settings, set the ```MTU``` to ```1420```. This is necessary because the traffic is routed through WireGuard, which reduces the packet size.\n\nIn case to use this configuration as a proxy server:\n\n- Set OS proxy settings to ```VPN_GATEWAY``` address and ports specified in the PROXY_HTTP_PORT/PROXY_SOCKS_PORT variables\n- Under linux set environment variables ```http_proxy```, ```https_proxy``` according your needs\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fn-r-w%2Fshadow-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fn-r-w%2Fshadow-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fn-r-w%2Fshadow-client/lists"}