{"id":18689570,"url":"https://github.com/misje/dhcpoptinj","last_synced_at":"2025-04-12T05:53:56.581Z","repository":{"id":35586275,"uuid":"39858942","full_name":"misje/dhcpoptinj","owner":"misje","description":"DHCP option injector","archived":false,"fork":false,"pushed_at":"2020-07-07T15:03:50.000Z","size":135,"stargazers_count":42,"open_issues_count":6,"forks_count":12,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-12T05:53:50.565Z","etag":null,"topics":["dhcp","dhcp-options","inject"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/misje.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2015-07-28T21:34:33.000Z","updated_at":"2025-04-01T09:28:34.000Z","dependencies_parsed_at":"2022-07-27T22:47:20.837Z","dependency_job_id":null,"html_url":"https://github.com/misje/dhcpoptinj","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/misje%2Fdhcpoptinj","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/misje%2Fdhcpoptinj/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/misje%2Fdhcpoptinj/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/misje%2Fdhcpoptinj/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/misje","download_url":"https://codeload.github.com/misje/dhcpoptinj/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248525156,"owners_count":21118616,"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":["dhcp","dhcp-options","inject"],"created_at":"2024-11-07T10:44:11.477Z","updated_at":"2025-04-12T05:53:56.558Z","avatar_url":"https://github.com/misje.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DHCP option injector\n[![Build Status](https://travis-ci.org/misje/dhcpoptinj.svg?branch=dev)](https://travis-ci.org/misje/dhcpoptinj) [![Total alerts](https://img.shields.io/lgtm/alerts/g/misje/dhcpoptinj.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/misje/dhcpoptinj/alerts/)\n\nHave you ever wanted to intercept DHCP requests and squeeze in a few extra DHCP\noptions, unbeknownst to the sender? Probably not. However, should the need ever\ncome, **dhcpoptinj** will (hopefully) help you.\n\n## Why\n\nThere can be many a reason to mangle DHCP requests, although chances are you\nought to look for a much better method for solving your problem. Perhaps you do\nnot have access to the DHCP server/clients and need to modify their DHCP\noptions, perhaps the DHCP software is difficult to configure (or does not\nsupport what you want to do), perhaps you have a very complex and/or odd setup,\nor perhaps you just want to experiment sending exotic or malformed options?\nThere is a small chance that dhcoptinj might actually be of some use.\n\n## How\n\ndhcpoptinj waits for packets to arrive in a netfilter queue. It will ensure\nthat a packet is in fact a BOOTP/DHCP packet, and if so proceed to inject\noptions. It will recalculate the IPv4 header checksum, disable the UDP\nchecksum (for a simpler implementation) and then give the packet back to\nnetfilter.\n\nYou need an iptables rule in order to intercept packets and send them to\ndhcpoptinj. Let us say you have two interfaces bridged together, *eth0* and\n*eth1*. Let us say you want to intercept all BOOTP requests coming from *eth0*\nand inject the [relay agent information\noption](https://tools.ietf.org/html/rfc3046) (82/0x52). Let us make up a silly\npayload: An [agent circuit ID\nsub-option](https://tools.ietf.org/html/rfc3046#section-3.1) with the value\n\"Fjas\".\n\nAdd a rule to the iptables mangle table:`sudo iptables -t mangle -A PREROUTING\n-m physdev --physdev-in eth0 -p udp --dport 67 -j NFQUEUE --queue-num 42`.\n\nThen run dhcpoptinj (let us run it in the foreground with extra debug output):\n`sudo dhcpoptinj -d -f -q 42 -o'52 01 04 46 6A 61 73'`. Note that dhcpoptinj\nmust be run by a user with the CAP\\_NET\\_ADMIN capability. You do not need to,\nand you really should not run dhcpoptinj as root. Instead, you can for instance\ngrant the CAP\\_NET\\_ADMIN capability to the binary (using *setcap*) and limit\nexecution rights to only a specific user or group. This is a method used for\nrunning wireshark as non-root, so you will find several guides helping you\naccomplish this.\n\nNow send a DHCP packet to the *eth0* interface and watch it (using a tool like\n[wireshark](https://www.wireshark.org/)) having been modified when it reaches\nthe bridged interface. It should have the injected option at the end of the\noption list. If you capture the incoming DHCP packet with Wireshark, it will\nappear unmodified although it will in fact be mangled.\n\nNote the format of the argument to the *-o* option: It should be a hexadecimal\nstring starting with the DHCP option code followed by the option payload. The\noption length (the byte that normally follows the option code) is automatically\ncalculated and must not be specified. The hex string can be delimited by\nnon-hexadecimal characters for readability. All options must have a payload,\nexcept for the special [pad\noption](https://tools.ietf.org/html/rfc2132#section-2) (code 0).\n\nThe layout of the nonsensical option used in this example (first the [DHCP\noption layout](https://tools.ietf.org/html/rfc2132#section-2), then the\nspecific [relay agent information option sub-option\nlayout](https://tools.ietf.org/html/rfc3046#section-2.0)) is as follows:\n\n| Code | Length |            Data            |\n|------|--------|----------------------------|\n|  52  | (auto) | 01 04 46 6A 61 73 (\"Fjas\") |\n\n| Sub-opt. | Length |         Data         |\n|----------|--------|----------------------|\n|    01    |   4    | 46 6A 61 73 (\"Fjas\") |\n\nNote that dhcpoptinj does not care about what you write in the option payloads,\nnor does it check whether your option code exists. It does however forbid you\nto use the option code 255 (the terminating end option). dhcpoptinj inserts\nthis option as the last option automatically.\n\n## Screenshot\n```\ndhcpoptinj -f -d -q42 -r -o'0C 66 6A 61 73 65 68 6F 73 74' -o'52 01 04 46 6A 61 73' -o 320A141E28\n```\n```\n3 DHCP option(s) to inject (with a total of 25 bytes): 12 (0x0C) (Hostname), 82 (0x52) (Relay Agent Information), 50 (0x32) (Address Request)\nExisting options will be removed\nInitialising netfilter queue\nInitialising signal handler\nInitialisation completed. Waiting for packets to mangle on queue 42\nReceived 416 bytes\nInspecting 328-byte DHCP packet from B6:40:FE:41:30:DC to 255.255.255.255:67\nMangling packet\nFound option  53 (0x35) (DHCP message type)        DHCPREQUEST (copying)\nFound option  54 (0x36) (DHCP Server Id)           with   4-byte payload 0A 14 1E 01 (copying)\nFound option  50 (0x32) (Address Request)          with   4-byte payload 0A 14 1E 28 (removing)\nFound option  12 (0x0C) (Hostname)                 with  12-byte payload 33 31 36 64 65 39 31 34 64 61 62 34 (removing)\nFound option  55 (0x37) (Parameter List)           with  13-byte payload 01 1C 02 03 0F 06 77 0C 2C 2F 1A 79 2A (copying)\nFound END option (removing)\nInjecting option  12 (0x0C) (Hostname)                 with   9-byte payload 66 6A 61 73 65 68 6F 73 74\nInjecting option  82 (0x52) (Relay Agent Information)  with   6-byte payload 01 04 46 6A 61 73\nInjecting option  50 (0x32) (Address Request)          with   4-byte payload 0A 14 1E 28\nInserting END option\nPadding with 10 byte(s) to meet minimal BOOTP payload size\nSending mangled packet\n\n```\n\n## Installing\n[![Packaging status](https://repology.org/badge/vertical-allrepos/dhcpoptinj.svg)](https://repology.org/project/dhcpoptinj/versions)\n\ndhcpoptinj is in Debian/Ubuntu. The deb package is under source control at\n[salsa](https://salsa.debian.org/misje-guest/dhcpoptinj). Installing\ndhcpoptinj from the deb package is recommended over the following manual\ninstallation procedure, because it also includes a man page, bash completion\nrules, example files etc. \n\n### Prerequisites\n\nYou need [cmake](http://www.cmake.org/) and\n[libnetfilter\\_queue](http://www.netfilter.org/projects/libnetfilter_queue/)\n(and a C compiler that supports C99). Hopefully, you are using a Debian-like\nsystem, in which case you can run the following to install them: `sudo apt-get\ninstall cmake libnetfilter-queue-dev`.\n\n### Build\n\n1. Download or clone the source: `git clone git://github.com/misje/dhcpoptinj`\n1. Enter the directory: `cd dhcpoptinj`\n1. Create a build directory and enter it (optional, but recommended): `mkdir\n\tbuild \u0026\u0026 cd build`\n1. Run cmake: `cmake ..` (or `cmake -DCMAKE_BUILD_TYPE=Debug ..` if you want a\n\tdebug build)\n1. Run make: `make -j4`\n1. Install (optional, but you will benefit from having dhcpoptinj in your\n\tPATH): `sudo make install`\n\n### Demolish\n\n1. Run `sudo make uninstall` from your build directory\n\nThe build directory with all its contents can be safely removed. If you did not\nuse a build directory, you can get rid of all the cmake rubbish by running `git\nclean -dfx`. Note, however, that this removes **everything** in the project\ndirectory that is not under source control.\n\n## Configuration file\n\ndhcptopinj will attempt to parse /etc/dhcpoptinj.conf or the file passed with\n-c/--conf-file. The syntax of the configuration file is\n* **key=value**, where *key* is the long option name, or\n* **key** if the option does not take an argument\n\nWhitespace is optional. Anything after and including the character **#** is\nconsidered a comment. DHCP options are listed one-by-one as *option=01:02:03*.\nQuotes around the option hex string is optional, and the bytes may be separated\nby any number of non-hexadecimal characters.\n\nThe options *version*, *help* and *conf-file* are not accepted in a\nconfiguration file.\n\nExample:\n```apache\n# Run in foreground:\nforeground\n# Enable debug output:\ndebug\n# Override hostname to \"fjasehost\":\noption = '0C 66 6A 61 73 65 68 6F 73 74'\n# Send agent ID \"Fjas\":\noption = \"52:01:04:46:6A:61:73\"\n# Override address request to ask for 10.20.30.40:\noption=320A141E28\n# Use queue 12:\nqueue = 12\n\nremove-existing-opt # Remove options before inserting\n```\n\n## Help\n\nThis readme should have got you started. Also check out the man page (in the\ndeb package) and the help output (`dhcpoptinj -h`), which should cover\neverything the utility has to offer.\n\nFor bugs and suggestions please create an issue.\n\n### Limitations\n\ndhcpoptinj is simple and will hopefully stay that way. Nonetheless, the\nfollowing are missing features that hopefully will be added some day:\n\n1. Remove options instead of having to replace them\n2. Filter incoming packets by their DHCP message type (code 53) before mangling\n\tthem\n\n### Troubleshooting\n\n1. *Failed to bind queue handler to AF_INET: Operation not permitted*\n\n\tMost likely you do not have CAP\\_NET\\_ADMIN capability or there is another\n\tprocess (perhaps another dhcpoptinj instance?) bound to the same netfilter\n\tqueue number.\n\n### Known issues\n\n1. Memory leak on non-normal exit.\n\n\tThis is not considered a leak. However, there should be no memory leak on a\n\tnormal exit (catching SIGTERM, SIGINT or SIGHUP).\n\n## Useful information\n\nWhen creating iptables rules to use with dhcpoptinj, the following options can\nbe useful:\n\n-\t`--queue-bypass`\n\n\tDo not drop packets, but let them pass through if dhcpoptinj is not running\n\t(or not listening on the correct queue number).\n\n## Contributing\n\nIf you have any suggestions please leave an issue, and I will come back to you.\nYou are welcome to contribute and pull requests are much appreciated.\n\nIf you find dhcpoptinj useful I would love to hear what you are using it for.\nUpdate the [wiki\npage](https://github.com/misje/dhcpoptinj/wiki#practical-use-cases) and\ndescribe your use.\n\n## License\n\nI have chosen to use GPL for this project. If that does not suit you, contact\nme, and we can agree on a different license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmisje%2Fdhcpoptinj","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmisje%2Fdhcpoptinj","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmisje%2Fdhcpoptinj/lists"}