{"id":19973260,"url":"https://github.com/zeromq/zmtpdump","last_synced_at":"2025-03-01T18:24:42.966Z","repository":{"id":66081782,"uuid":"43621968","full_name":"zeromq/zmtpdump","owner":"zeromq","description":"ZeroMQ Transport Protocol packet analyzer","archived":false,"fork":false,"pushed_at":"2018-01-18T15:06:18.000Z","size":176,"stargazers_count":26,"open_issues_count":5,"forks_count":11,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-01-12T09:30:30.574Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Roff","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zeromq.png","metadata":{"files":{"readme":"README","changelog":"ChangeLog","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":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-10-04T02:10:39.000Z","updated_at":"2024-07-06T11:09:11.000Z","dependencies_parsed_at":"2023-07-08T13:00:42.902Z","dependency_job_id":null,"html_url":"https://github.com/zeromq/zmtpdump","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeromq%2Fzmtpdump","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeromq%2Fzmtpdump/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeromq%2Fzmtpdump/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeromq%2Fzmtpdump/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zeromq","download_url":"https://codeload.github.com/zeromq/zmtpdump/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241406047,"owners_count":19957944,"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":[],"created_at":"2024-11-13T03:10:49.511Z","updated_at":"2025-03-01T18:24:42.953Z","avatar_url":"https://github.com/zeromq.png","language":"Roff","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zmtpdump, ZMTP packet analyzer\n\n## Introduction\n\nzmtpdump is a packet analyzer (also known as sniffer) of ZeroMQ Transport\nProtocol. It currently supports ZMTP 3.0 only.\n\nzmtpdump is meant to be used for the purpose of learning the low-level\ndetails of ZeroMQ and for any time you need to analyze ZeroMQ communication,\nfor example when debugging.\n\nCurrently, zmtpdump runs and has been tested on Linux. Contributions for\nother *nix flavors or other OSes are welcome.\n\n## License\n\nThis project uses the MPL v2 license, see LICENSE.\n\n### What zmtpdump does\n\nzmtpdump listens on the specified network interface and ports and reports\non what information is exchanged, from establishment of connection to\nexchanging messages.\n\n### What zmtpdump does not do\n\n* It does not support older versions of ZMTP (1.0 and 2.0).\n* It does not currently support other security mechanism than NULL (ZMTP\nspecification mentions PLAIN and CURVE).\n* It does not support other transports than TCP, such as Unix sockets.\n\n## Building and installing\n\nBuild and install zmtpdump by doing this:\n\n    ./configure\n    make\n    make install\n\nRun unit test by executing\n\n    make check\n\n## Usage\n\nRun zmtpdump without any parameters and it displays this help message:\n\n```\nzmtpdump\nZMTP packet analyzer\nUsage: zmtpdump -i \u003cinterface\u003e [ -vh ] \u003cfilter\u003e\n  -i \u003cinterface\u003e - capture packets on specified interface\n                   (e.g. lo or eth0)\n  -v             - verbose - report TCP packets with flags,\n                   such as SYN/ACK/PSH/RST\n  -h             - this message\n  \u003cfilter\u003e       - filter that specifies what packets we capture\n                   Examples:\n                     - port 7001\n                     - port 7001 or port 7002\n```\n\nFor example, if you want to listen on loopback interface, ports 7001 and\n7002, the command looks like this:\n\n    sudo zmtpdump -i lo \"port 7001 or port 7002\"\n\nThe syntax for filter is the same as for the expression for tcpdump, which\nis the syntax of pcap filters.\n\nNote that zmtpdump has to be run as root or with sudo, because network\npacket capturing is considered privileged operation.\n\n## Contribution process\n\n* C4 process is at http://rfc.zeromq.org/spec:16.\n* All commits are be backed by issues.\n* All commits are made as pull requests from forked work repository.\n\n### Verbose flag\n\nBy default, zmtpdump works in non-verbose mode where it reports only ZMTP\ninformation. If you want to see TCP packet flags for better understanding\nof the connections, use -v flag. In verbose mode zmtpdump will report on\nall TCP packets, so you can see as a TCP connection is being established\nwith three-way handshake (SYN-SYN/ACK-ASK) through to the connection\nteardown (FIN-FIN/ACK-ACK).\n\nYou will probably want to use non-verbose mode most of the time, because\nthe verbose mode may flood you with packets that are not ZMTP packets.\nMost significantly, in ZeroMQ the side that is doing the connect (as\nopposed to bind) will attempt the connection many times per second, and if\nthe binding side is not currently running, you will see lots of\nSYN-RST packet pairs.\n\n## ZMTP\n\nFrom ZMTP documentation:\n\nA ZMTP connection goes through these main stages:\n\n* The two peers agree on the version and security mechanism of the\nconnection by sending each other data and either continuing the\ndiscussion, or closing the connection.\n* The two peers handshake the security mechanism by exchanging zero or\nmore commands. If the security handshake is successful, the peers\ncontinue the discussion, otherwise one or both peers closes the\nconnection.\n* Each peer then sends the other metadata about the connection as a\nfinal command. The peers may check the metadata and each peer decides\neither to continue, or to close the connection.\n* Each peer is then able to send the other messages. Either peer may at\nany moment close the connection.\n\n## Example of use with PUSH-PULL messages\n\nAs probably the simplest ZeroMQ pattern, let's look at a PUSH-PULL pair.\nThere are two programs running on the localhost, one (receiver)\ncreates a PULL socket and binds to port 7001 and the other one (sender)\ncreates a PUSH socket and connects to port 7001. After that the sender\nsends a string message every 2 seconds. The messages that it sends are\nnumbers converted to strings: \"1\", \"2\", \"3\" and so on. (Note that it\ndoesn't send the terminating null byte, because ZeroMQ messages contain\nthe length of message. If the receiving side is a C program that wants to\nuse the received message as a string, it has to append the terminating null.)\n\nThe command to run zmtpdump is:\n\n    sudo zmtpdump -v -i lo \"port 7001\"\n\nWe are running zmtpdump in verbose mode so we can show the TCP negotiation\nalongside ZMTP packets.\n\nImportantly, we start the receiver first, and the sender second. If we do\nthe opposite, everything will work, but the output of zmtpdump will show\na lot of junk before we start the receiver (SYN-RST/ACK message-response\npairs).\n\nsender and receiver are included in this project, for basic test of\nzmtpdump. The source files are sender.c and receiver.c, and both programs\nare built together with zmtpdump executable and unit test test_zmtpdump\nby invoking make.\n\nHere is the output of zmtpdump:\n\n```\nVerbose\nFilter: port 7001\nInterface: lo\n----------------------------\n12:13:35.584\nPacket size: 74 bytes\nPayload size: 0 bytes\n[127.0.0.1:47563, 127.0.0.1:7001] SYN \n----------------------------\n12:13:35.584\nPacket size: 74 bytes\nPayload size: 0 bytes\n[127.0.0.1:7001, 127.0.0.1:47563] SYN ACK \n----------------------------\n12:13:35.584\nPacket size: 66 bytes\nPayload size: 0 bytes\n[127.0.0.1:47563, 127.0.0.1:7001] ACK \n----------------------------\n12:13:35.584\nPacket size: 76 bytes\nPayload size: 10 bytes\n[127.0.0.1:7001, 127.0.0.1:47563] ACK PSH \n----------------------------\n12:13:35.584\nPacket size: 76 bytes\nPayload size: 10 bytes\n[127.0.0.1:47563, 127.0.0.1:7001] ACK PSH \n----------------------------\n12:13:35.584\nPacket size: 66 bytes\nPayload size: 0 bytes\n[127.0.0.1:47563, 127.0.0.1:7001] ACK \n----------------------------\n12:13:35.584\nPacket size: 66 bytes\nPayload size: 0 bytes\n[127.0.0.1:7001, 127.0.0.1:47563] ACK \n----------------------------\n12:13:35.584\nPacket size: 67 bytes\nPayload size: 1 bytes\n[127.0.0.1:47563, 127.0.0.1:7001] ACK PSH \n----------------------------\n12:13:35.584\nPacket size: 67 bytes\nPayload size: 1 bytes\n[127.0.0.1:7001, 127.0.0.1:47563] ACK PSH \n----------------------------\n12:13:35.584\nPacket size: 119 bytes\nPayload size: 53 bytes\n[127.0.0.1:7001, 127.0.0.1:47563] ACK PSH \n[127.0.0.1:7001, 127.0.0.1:47563]: Analyzing greeting\n[127.0.0.1:7001, 127.0.0.1:47563]: Signature\n[127.0.0.1:7001, 127.0.0.1:47563]: Version: 03.00\n[127.0.0.1:7001, 127.0.0.1:47563]: Mechanism: NULL\n[127.0.0.1:7001, 127.0.0.1:47563]: as-server: 0\n[127.0.0.1:7001, 127.0.0.1:47563]: Filler\n----------------------------\n12:13:35.584\nPacket size: 119 bytes\nPayload size: 53 bytes\n[127.0.0.1:47563, 127.0.0.1:7001] ACK PSH \n[127.0.0.1:47563, 127.0.0.1:7001]: Analyzing greeting\n[127.0.0.1:47563, 127.0.0.1:7001]: Signature\n[127.0.0.1:47563, 127.0.0.1:7001]: Version: 03.00\n[127.0.0.1:47563, 127.0.0.1:7001]: Mechanism: NULL\n[127.0.0.1:47563, 127.0.0.1:7001]: as-server: 0\n[127.0.0.1:47563, 127.0.0.1:7001]: Filler\n----------------------------\n12:13:35.585\nPacket size: 94 bytes\nPayload size: 28 bytes\n[127.0.0.1:7001, 127.0.0.1:47563] ACK PSH \n[127.0.0.1:7001, 127.0.0.1:47563]: READY command\n[127.0.0.1:7001, 127.0.0.1:47563]: property: \"Socket-Type\" 53 6f 63 6b 65 74 2d 54 79 70 65\n[127.0.0.1:7001, 127.0.0.1:47563]: value: \"PULL\" 50 55 4c 4c\n----------------------------\n12:13:35.585\nPacket size: 94 bytes\nPayload size: 28 bytes\n[127.0.0.1:47563, 127.0.0.1:7001] ACK PSH \n[127.0.0.1:47563, 127.0.0.1:7001]: READY command\n[127.0.0.1:47563, 127.0.0.1:7001]: property: \"Socket-Type\" 53 6f 63 6b 65 74 2d 54 79 70 65\n[127.0.0.1:47563, 127.0.0.1:7001]: value: \"PUSH\" 50 55 53 48\n----------------------------\n12:13:35.585\nPacket size: 69 bytes\nPayload size: 3 bytes\n[127.0.0.1:47563, 127.0.0.1:7001] ACK PSH \n[127.0.0.1:47563, 127.0.0.1:7001]: message: \"1\" 31\n----------------------------\n12:13:35.585\nPacket size: 66 bytes\nPayload size: 0 bytes\n[127.0.0.1:7001, 127.0.0.1:47563] ACK \n----------------------------\n12:13:37.583\nPacket size: 69 bytes\nPayload size: 3 bytes\n[127.0.0.1:47563, 127.0.0.1:7001] ACK PSH \n[127.0.0.1:47563, 127.0.0.1:7001]: message: \"2\" 32\n----------------------------\n12:13:37.618\nPacket size: 66 bytes\nPayload size: 0 bytes\n[127.0.0.1:7001, 127.0.0.1:47563] ACK \n----------------------------\n12:13:39.583\nPacket size: 69 bytes\nPayload size: 3 bytes\n[127.0.0.1:47563, 127.0.0.1:7001] ACK PSH \n[127.0.0.1:47563, 127.0.0.1:7001]: message: \"3\" 33\n----------------------------\n12:13:39.583\nPacket size: 66 bytes\nPayload size: 0 bytes\n[127.0.0.1:7001, 127.0.0.1:47563] ACK \n----------------------------\n12:13:39.930\nPacket size: 66 bytes\nPayload size: 0 bytes\n[127.0.0.1:47563, 127.0.0.1:7001] ACK FIN \n----------------------------\n12:13:39.930\nPacket size: 66 bytes\nPayload size: 0 bytes\n[127.0.0.1:7001, 127.0.0.1:47563] ACK FIN \n----------------------------\n12:13:39.930\nPacket size: 66 bytes\nPayload size: 0 bytes\n[127.0.0.1:47563, 127.0.0.1:7001] ACK \n```\n\nHere you can see all packets, from the establishment of connection with\nthe three-way TCP handshake (SYN-SYN/ACK-ACK), through the negotiation and\nmessage exchange, to closing of TCP connection.\n\nIn the above output, packet size is the size of the whole captured packet,\nwhich includes ethernet header, IP header, TCP header and TCP payload.\nPayload size is the size of payload data.\n\nNote that there are some packets that have payload size greater than 0, but\nno ZMTP packet is shown. That happens when the sending side sent some\nbytes but zmtpdump has not seen a whole packet, so it will just buffer the\nreceived data until it assembles a full ZMTP packet.\n\n## Unit test\n\nzmtpdump was developed TDD-style, bottom-up, starting with a buffer for\naccumulating received bytes. The unit test reflects that and you can run\nit by executing\n\n    make check\n\nTest data for unit test were collected using sender and receiver programs and\nWireshark.\n\n## References\n\n* ZMTP spec: http://zmtp.org/page:read-the-docs\n* libpcap: http://www.tcpdump.org/pcap.html\n* ZeroMQ home page: http://zeromq.org\n* Wireshark: http://wireshark.org\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzeromq%2Fzmtpdump","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzeromq%2Fzmtpdump","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzeromq%2Fzmtpdump/lists"}