.\" .\" bittwist.1 - manpage for the bittwist program .\" Copyright (C) 2006 - 2012 Addy Yeow Chin Heng .\" .\" This program is free software; you can redistribute it and/or .\" modify it under the terms of the GNU General Public License .\" as published by the Free Software Foundation; either version 2 .\" of the License, or any later version. .\" .\" This program is distributed in the hope that it will be useful, .\" but WITHOUT ANY WARRANTY; without even the implied warranty of .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the .\" GNU General Public License for more details. .\" .\" You should have received a copy of the GNU General Public License .\" along with this program; if not, write to the Free Software .\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. .\" .TH BITTWIST 1 "21 April 2012" .SH NAME .B bittwist \-- pcap based ethernet packet generator .SH SYNOPSIS .B bittwist [ .B \-dvh ] [ .B \-i .I interface ] [ .B \-s .I length ] [ .B \-l .I loop ] .ti +9 [ .B \-c .I count ] [ .B \-m .I speed ] [ .B \-r .I rate ] [ .B \-p .I sleep ] .ti +9 .I pcap-file(s) .SH DESCRIPTION This document describes the \fIbittwist\fP program, the \fIpcap\fP(3) based Ethernet packet generator. \fIBittwist\fP is designed to work under Ethernet II (IEEE 802.3) network with a MTU of up to 1500 bytes on 10Mbps (10Base-T Ethernet) or 100Mbps (Fast Ethernet) link speed. Packets are generated from saved \fItcpdump\fP(1) capture file referred to as trace file in this document. Some familiarity with \fItcpdump\fP(1) and its basic options are assumed in this document. Since \fIbittwist\fP uses functions provided by \fIpcap\fP(3) library, e.g. \fBpcap_open_live()\fP and \fBpcap_inject()\fP, to write packets onto the network, it may require that you have special privileges, e.g. read access to \fI/dev/bpf*\fP on BSD or root access on Linux, to generate packets or to enumerate network devices with, for example, the \fB-d\fP flag. .PP \fIBittwist\fP will, if not run with the \fB-s\fP flag, inject each packet up to its actual length (on-wire) instead of its captured length. If the captured length is less than the actual length, \fIbittwist\fP will pad the packet with zeros up to its actual length prior to injection. \fIBittwist\fP will, if not run with the \fB-m\fP, \fB-r\fP, or \fB-p\fP flag, inject packets from a trace file based on the captured intervals, in particular, the timestamp difference between two adjacent packets, except for the first packet in a trace file, which is always injected immediately. \fIBittwist\fP is designed to not to interfere with the packet data; it merely read a packet and inject it as is onto the network. If modification is desired prior to injection of a packet, you can use the \fIbittwiste\fP(1) program, which does just that. .SH OPTIONS .TP .B \-d Print a list of network interfaces available. .TP .B \-v Print timestamp for each packet. .TP .B \-vv Print timestamp and hex data for each packet. .TP .B \-i \fIinterface\fP Send \fIpcap-file(s)\fP out onto the network through \fIinterface\fP. .TP .B \-s \fIlength\fP Packet length to send. Set \fIlength\fP to: .IP .br 0 to send the actual packet length. This is the default. .br -1 to send the captured length. .IP or any other value from 14 to 1514. .TP .B \-l \fIloop\fP Send \fIpcap-file(s)\fP out onto the network for \fIloop\fP times. Set \fIloop\fP to 0 to send \fIpcap-file(s)\fP until stopped. To stop, type Control-C. .TP .B \-c \fIcount\fP Send up to \fIcount\fP packets. Default is to send all packets from \fIpcap-file(s)\fP. .TP .B \-m \fIspeed\fP Set interval multiplier to \fIspeed\fP. Set \fIspeed\fP to 0 or less to send the next packet immediately. Minimum positive value for \fIspeed\fP is 0.000001. .TP .B \-r \fIrate\fP Limit the sending to \fIrate\fP Mbps. Value for \fIrate\fP must be between 1 to 1000. This option is meant to limit the maximum packet throughput. If you want to send packets at line rate of 100Mbps, try -m 0 -r 100 .TP .B \-p \fIsleep\fP Set interval to \fIsleep\fP (in seconds), ignoring the actual interval. Value for \fIsleep\fP must be between 1 to 2146. .TP .B \-h Print version information and usage. .SH SEE ALSO bittwiste(1), pcap(3), tcpdump(1) .SH BUGS File your bug report and send to: .IP Addy Yeow Chin Heng .PP Make sure you are using the latest stable version before submitting your bug report. .PP If you run \fIbittwist\fP with \fB-m\fP flag set to 0 without limiting the throughput with \fB-r\fP flag, \fBpcap_inject\fP() may return an error with the following error string: .IP send: No buffer space available .PP We recommend that you specify the \fB-r\fP flag to limit the packet throughput, e.g. \fB-m\fP 0 \fB-r\fP 100 to inject packets at a maximum rate of 100Mbps. .SH COPYRIGHT Copyright (C) 2006 - 2012 Addy Yeow Chin Heng .PP This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or any later version. .PP This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. .PP You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. .SH AUTHORS Original author and current maintainer: .IP Addy Yeow Chin Heng .PP The current version is available from http://bittwist.sourceforge.net