{"id":24449184,"url":"https://github.com/codeniko/vtundfix","last_synced_at":"2025-10-06T04:48:53.610Z","repository":{"id":11174340,"uuid":"13550034","full_name":"codeniko/vtundfix","owner":"codeniko","description":"Service to ensure uptime of Virtual Tunnel (VTun) for Rutger's University computer network","archived":false,"fork":false,"pushed_at":"2018-03-03T21:31:40.000Z","size":20,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-14T05:43:21.802Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Shell","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/codeniko.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}},"created_at":"2013-10-14T01:29:05.000Z","updated_at":"2018-03-03T01:01:46.000Z","dependencies_parsed_at":"2022-09-04T06:20:24.086Z","dependency_job_id":null,"html_url":"https://github.com/codeniko/vtundfix","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/codeniko/vtundfix","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeniko%2Fvtundfix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeniko%2Fvtundfix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeniko%2Fvtundfix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeniko%2Fvtundfix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codeniko","download_url":"https://codeload.github.com/codeniko/vtundfix/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeniko%2Fvtundfix/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278561275,"owners_count":26006954,"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","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2025-01-21T00:37:36.578Z","updated_at":"2025-10-06T04:48:53.579Z","avatar_url":"https://github.com/codeniko.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vtundfix / Vtundctl\nVtundfix is a service written in bash to keep Vtund up and running. Occasionally, the tunnel between Rutgers LCSR and CBIM would go down for an unknown reason and would require a manual restart. Vtundfix is a general solution which detects if any component of the tunnel (bridge/vlan/tap interfaces, processes) is not working, and fixes the problem that is detected. \n\nVtundctl is a control script that merges the commands and init commands of Vtund and Vtundfix. Usage of Vtundctl can be found in subsection **Using Vtundfix and Vtundctl**.\n\n\n## Installation\nVtundfix needs to be installed on both the Vtund server and client machines. Download or pull a copy of this repo and just run make. `make install` will put all of the files in the correct locations.\n\u003e make install\n\n## Configuration\nVtundfix configuration. Here are the contents of the template file:\n\u003e cat /etc/vtundfix.conf\n\n\u003cpre\u003e\nDIRECTORY /usr/local/vtundfix/\nDELAY_BETWEENCHECK 300\nDELAY_PARENTCHECK 300\nSERVER 192.168.10.5\nMACHINE client\nEMAIL example@example.com\n\n\u003ctap\u003e \u003ctun name\u003e \u003cclient ip\u003e \u003cbridge\u003e \u003cvlan for bridge\u003e\n\ntap0 lcsr 192.168.1.100 br0 eth0.763\ntap1 lcsr2 192.168.1.101 br1 eth0.764\n\u003c/pre\u003e\n\n### General Settings\n\nHere is a description of all the settings:\n\u003cpre\u003e\nDIRECTORY - Directory containing the actual files for Vtundfix. Avoid changing the default value of \nthis if possible.\n\u003c/pre\u003e\u003cpre\u003e\nDELAY_BETWEENCHECK - Delay between checks of whether or not Vtund and its components are working. \nThe value is in seconds. The default is 300 seconds.\n\u003c/pre\u003e\u003cpre\u003e\nDELAY_PARENTCHECK - Delay between checks of whether or not children processes of Vtundfix are running. \nIf not, that child is restarted to ensure that everything is working correctly. Each child of Vtundfix \nperforms detection/correction checking for a unique TAP interface. The value is in seconds. The default\nis 300 seconds.\n\u003c/pre\u003e\u003cpre\u003e\nSERVER - The IP address of the Vtund server machine. For consistancy, have this setting in the Server \nmachine too.\n\u003c/pre\u003e\u003cpre\u003e\nMACHINE - Specify if the local machine is a Vtund \"server\" or \"client\". The valid values for this are \n\"server\" and \"client\".\n\u003c/pre\u003e\u003cpre\u003e\nEMAIL - The e-mail address to send a notification to when the TAP interface has been restarted. An \ne-mail is only sent if it is related to the TAP interface. This excludes bridge or process problems.\n\u003c/pre\u003e\n\n### TAP Interface Configuration\nThe format for configuring the TAP interfaces at the bottom of the configuration file is as follows.\n\u003cpre\u003e\n\u0026lt;tap\u0026gt; \u0026lt;tunnel/session name\u0026gt; \u0026lt;client ip\u0026gt; \u0026lt;bridge\u0026gt; \u0026lt;vlan for bridge\u0026gt;\n\u003c/pre\u003e\nThe following are examples. Each new TAP configuration should be on a separate line.\n\u003cpre\u003e\ntap0 lcsr 192.168.1.100 br0 eth0.763\ntap1 lcsr2 192.168.1.101 br1 eth0.764\n\u003c/pre\u003e\n\nWhat I just configured was a TAP interface with *identifier 0*, with a tunnel name of *lcsr*. This TAP interface is bridged with *vlan 763* on eth0 through the *br0* br\nidge. Finally, the IP address of the client that establishes this connection is 192.168.1.100.\nTap1 is similar but with just different values. Of course, replace these values with your existing Vtund values. When doing these configurations, each of these values should remain constant. For example, the client configured to connect as tap0 shouldn't be assigned tap1. In **/etc/vtund.conf** of **both** Vtund server and client, make sure that the lcsr session is to be assigned a specific tap interface and that the persist settings are set. The persist and multi settings are required to be on for Vtundfix to work properly. Apply these settings for **every** tunnel name in **/etc/vtund.conf**.\n\u003cpre\u003e\nPortion of /etc/vtund.conf to make sure it's set (add if it's not): \n\u003c/pre\u003e\n\u003cpre\u003e\nlcsr {\n    persist yes;\n    device tap0;\n    multi killold;\n}\n\u003c/pre\u003e\n\n### Setup SSH Authentication with Keys\nIn order for Vtundfix to work, create the *vtundfix* user on each machine and set it up to SSH into the *vtundfix* user on the other machine without the password prompt. Do the following commands on both machines\n\nCreate the *vtundfix* user and maybe send the password:\n\u003e useradd vtundfix \u003cbr\u003e\n\u003e passwd vtundfix\n\nCreate a key for the **vtundfix** users (first switch user):\n\u003e su vtundfix\n\u003e ssh-keygen -t rsa\n\n\nOnce you have a key for both machines, copy the key from one into the authorized file of the other. Do so for both:\n\u003e cat ~/.ssh/id_rsa.pub | ssh vtundfix@IP_OF_OTHER_MACHINE \"cat \u003e\u003e ~/.ssh/authorized_keys\"\n\nNext, change permissions of the following files/directories in each *vtundfix* user:\n\u003e chmod 700 ~/.ssh \u003cbr\u003e\n\u003e chmod 600 ~/.ssh/id_rsa \u003cbr\u003e\n\u003e chmod 600 ~/.ssh/authorized_keys\n\nTest to see if you can SSH successfully without the password prompt from the *vtundfix* users.\n\u003e ssh vtundfix@IP_OF_OTHER_MACHINE\n\nIf it is still not working, edit **/etc/ssh/sshd_config** and make sure the following is uncommented. Add it if it's not there.\n\u003cpre\u003e\nRSAAuthentication yes\nPubkeyAuthentication yes\n\u003c/pre\u003e\nFinally, restart the SSH service:\n\u003e /etc/init.d/sshd restart\n\n## Setup Cron\nIf a linux machine can't start any new processes because there are too many processes running, processes start to die randomly. If the parent process of Vtundfix is ever killed, the children die and there will be nothing to check and make sure that the Vtund tunnels are up and running. Vtundfix comes with a small script, **/usr/local/vtundfix/vtundfix_cron**, that restarts Vtundfix if it *should* be running. Although this step might seem optional, it is recommended for the longevity of the program.\n\nThe cron script is by default already set up when you untar *vtundfix.tgz* and the script is set to run every 5 minutes. When you untar, you should restart the cron daemon.\n\u003e /etc/init.d/crond stop\u003cbr\u003e\n\u003e /etc/init.d/crond start\n\nIf you want to change how often the script runs or remove it, the crontab file is located in **/usr/local/vtundfix/vtundfix_crontab** and is linked from **/etc/cron.d/vtundfix**\n\n## Using Vtundfix and Vtundctl\nThis section will show you the basic commands. To get more specific information on Vtundfix commands, take a look at `man vtundfix`\n\n**Starting Vtundfix** \u003cbr\u003e\nStarting Vtundfix will start the tunnel checks for all TAP interfaces specified in */etc/vtundfix.conf*. You can start Vtundfix from one of the following methods (Vtundctl commands will be further explained in the next section): \n\u003e vtundctl fix start\n\n**Stopping Vtundfix** \u003cbr\u003e\nStopping Vtundfix will stop the tunnel checks for *all* TAP interfaces. To stop Vtundfix, type:\n\u003e vtundctl fix stop\n\nIdeally, starting and stopping is all you really need to manage Vtundfix. However, you might need more control sometimes. Suppose you have two TAP interfaces configured, tap0 and tap1, and you want to have Vtundfix only check tap0 temporarily. You can turn off Vtundfix for tap1 by doing this:\n\u003e vtundctl fix off tap1\n\nThis will turn off checking on **both** the Vtund server and client machines. To turn it back on, do this\n\u003e vtundctl fix on tap1\n\n\nVtundctl merges the commands for Vtund and Vtundfix, along with their init script commands.\nHere is an example of calling a command for **Vtund** through Vtundctl and what it does:\n\u003e vtundctl vtund lcsr 192.168.1.100  # *start Vtund client process that will attempt to connect to Vtund server*\n\n## Inside Vtundfix (How it works)\nThis section will cover how Vtundfix works on the inside incase changes need to be made or something weird is happening.\n\n**NOTE** Vtundfix requires the ability to SSH to **server \u003c---\u003e client** as the *vtundfix* user in both directions and with an SSH authentication key (there should be no password prompt). The client and server require data from each other to function correctly.\n\nWhenever Vtundfix is run, it first reads the configuration file. All of the settings in the example configuration file **MUST** be there. Do not omit any of the settings or else something unknown might happen. When Vtundfix is started, the main parent process spawns a child for every TAP interface configured in the configuraiton file. Each child is responsible for it's unique TAP interface. It does checks, and fixes any problems that might arise for that specific interface. Therefore, if something was to happen to one TAP interface, the other TAP interfaces are still being looked after. They are independent.\n\nThe parent process has one main responsibility. It is to make sure that its child processes are running. If a child randomly dies, it will be respawned with the correct TAP interface. If the parent ever dies when it is *SUPPOSED* to be running, the **vtundfix_cron** script is designed to bring it back up.\n\nThe child processes are what actually do all of the work for Vtundfix. The first thing that a child does is check if its parent is still alive. If the child is actually a zombie, it will terminate itself. If that's ok, the child follows a sequence of checks based on whether the local machine is a *server* or a *client*. This is looped with a delay specified in the configuration file.\n\n1. If the machine is a client, check if the Vtund TAP connection process is running. \u003cbr\u003e\n2. On both server/client, check if VLAN exists locally.\u003cbr\u003e\n3. On both server/client, check if the Bridge exists locally.\u003cbr\u003e\n4. On client, check if the TAP interface exists.\u003cbr\u003e\n5. On both server/client, check if the TAP interface is working. If server and the TAP isn't working, do not continue (bridge will show up as not working). If client, restart the tap interface.\u003cbr\u003e\n6. On both server/client, check if the Bridge is working locally.\u003cbr\u003e\n7. If the machine is a server, check if the Vtund listener process is running\u003cbr\u003e\u003cbr\u003e\n\nIf a problem is detected as Vtundfix does those checks in order, the problem is fixed and the check sequence restarts after another delay. It will not continue down the checks until that problem is resolved.\n\nChecking if the VLAN exists is done as follows. First, check if the actual interface itself exists (eth0.763). Then check if this interface is up. Finally, check if this interface (eth0.763) is tied to the correct Device name (eth0) and correct VLAN ID (763)\n\nChecking if the Bridge exists is done as follows. First, check if the actual interface itself exists (br0). Then check if this interface is up. Finally, check if this bridge (br0) is configured correctly and actually bridges the TAP interface (tap0) and the VLAN interface (eth0.763).\n\nTo determine if the TAP interfaces are working and data is actually flowing through the tunnel, Vtundfix checks the TX/RX packet counts that can be found when running *ifconfig*. Both the vtundfix client and server check these numbers both locally, and on the remote server. A copy of these numbers is then stored in the data files for each TAP interface to be used as the *previous* numbers to compare to. The idea behind Vtundfix is: if a packet was sent from one end and increased the TX count, then the RX count on the reciever should increase. It has been decided that the TAP interface is considered **NOT** working if data is not flowing through both directions of the tunnel. In other words, The tunnel is considered working if the TX/RX count increases on any side within *two* Vtundfix checks (delayed by the setting in the configuration file). There is a difference in how the client performs and how the server performs if there is an issue. When an issue rises, the client will restart the tunnel, but the server will simply ignore it and NOT check the bridge (the bridge will show up *broken* in this case, and this avoids an unnecessary restart).\n\n## Files Associated With Vtundfix\n/usr/local/vtundfix/vtundfix.conf\n\u003cpre\u003eThe  configuration  file  for  Vtundfix.  Should  be linked from /etc/vtundfix.conf.\u003c/pre\u003e\n/usr/local/vtundfix/vtundfix_init\n\u003cpre\u003eThe init script. Should be linked from /etc/init.d/vtundfix.\u003c/pre\u003e\n/usr/local/vtundfix/vtundfix\n\u003cpre\u003eThe  main  script  for   vtundfix.   Should   be   linked   from /usr/sbin/vtundfix.\u003c/pre\u003e\n/usr/local/vtundfix/vtundctl\n\u003cpre\u003eThe  control  script  which merges vtundfix and vtund. Should be linked from /usr/sbin/vtundctl\u003c/pre\u003e\n/var/vtundfix/vtundfix.log\n\u003cpre\u003eThe log file\u003c/pre\u003e\n/usr/local/vtundfix/vtundfix_cron\n\u003cpre\u003eThe cron file that makes sure the vtundfix daemon is running  as it’s supposed to. Should be linked from /etc/cron.d/vtundfix\u003c/pre\u003e\n/usr/local/vtundfix/vtundfix_logrotate\n\u003cpre\u003eThe logrotate file. Should be linked from /etc/logrotate.d/vtundfix\u003c/pre\u003e\n/var/vtundfix/data_tap#\n\u003cpre\u003eThe data files used by Vtundfix. If Vtundfix is configured with tap0 and tap1, there will be two data files. One data_tap0 and the other data_tap1\u003c/pre\u003e\n/var/run/vtundfix.pid\n\u003cpre\u003eThe PID file for vtundfix.\u003c/pre\u003e\n\n## Tunnel Notes\nVtund client triggers connection to server. When you start a client, a connector process is created that attempts to connect to the server every couple of seconds. When the server is started, a process is created that only listens for incoming client connections. Once a connection is triggered by the client and the connection becomes active, the TAP interface is created. The server will also spawn a new process that looks similar to the process in the client, which has a description of the connection. The only difference is if the connection ever goes goes down, the server's TAP process dies, but the client's process attempts to re-establish a connection again.\n\nWhen a connection is established, there is about a 16-18 packet handshake that Vtund does before traffic can actually flow through the tunnel.\n\nWhen a connection is broken, but the processes are still running, Vtund does nothing for a random amount of minutes and it appears as if the connection is still active. After the random timeout ends, Vtund client turns off the TAP interface and attempts to reconnect. When the Vtund server times out, the TAP process is just killed. Something to note is that the server and clients are independent and could timeout at random times. Prior to Vtundfix, the Vtund configuration could cause further delays when this happens, because you can't wait for one to timeout; they both have to timeout and they do this randomly. The Vtund configuration change that comes with Vtundfix utilizes the \"killold\" option which allows the server to terminate the old connection if a new client attempts to reconnect (Ex: if the client times out first).\nThe random timeout could range from 2 minutes to 15 minutes.\n\nThe killold option added by the addition of Vtundfix brings a new possible problem to be aware of: two client processes battling for the same connection. If by accident two client processes are created (even if they are created months apart), they will start to fight for the connection by killing each other's connection. It will be a never ending loop. This is something to be aware of, even though Vtundfix handles duplicate client processes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeniko%2Fvtundfix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodeniko%2Fvtundfix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeniko%2Fvtundfix/lists"}