README

Name:		force_bind

Author:		Catalin(ux) M. BOIE - catab at embedromix dot ro

Start date:	2010-10-26

Description:	Force binding on a specific IP and/or port.
		Plus forcing setsockopt calls on the socket.
		Works with both IPv4 and IPv6.
		It is useful if you have a binary application without sources
		and without the possibility to configure address or port to
		bind to.

License:	GPLv3

How it works:	force_bind is a shared object that is loaded with LD_PRELOAD and hooks 'bind' function.
		Forcing an IP/port to bind to is done with environments variables.

Examples:
		0. Output debug stuff in a log file (for debugging):
		export FORCE_NET_VERBOSE=999
		export FORCE_NET_LOG="xxx.log"
		export LD_PRELOAD=${LD_PRELOAD}:/usr/lib/force_bind.so
		your_program_here

		1. Force bind to 127.0.0.1, port 33, verbose operations:
		export FORCE_NET_VERBOSE=1
		export FORCE_BIND_ADDRESS_V4=127.0.0.1
		export FORCE_BIND_PORT_V4=33
		export LD_PRELOAD=${LD_PRELOAD}:/usr/lib/force_bind.so
		your_program_here

		2. Force binding to 127.0.0.2, port unchanged
		export FORCE_BIND_ADDRESS_V4=127.0.0.2
		export LD_PRELOAD=${LD_PRELOAD}:/usr/lib/force_bind.so
		your_program_here

		3. Force binding to ::1 (IPv6), port unchanged
		export FORCE_BIND_ADDRESS_V6=::1
		export LD_PRELOAD=${LD_PRELOAD}:/usr/lib/force_bind.so
		your_program_here

		4. Changing TOS on all sockets to 30
		export FORCE_NET_TOS=30
		export LD_PRELOAD=${LD_PRELOAD}:/usr/lib/force_bind.so
		your_program_here

		5. Force Keep alive to 60 seconds:
		export FORCE_NET_KA=60
		export LD_PRELOAD=${LD_PRELOAD}:/usr/lib/force_bind.so
		your_program_here

		6. Force MSS to 1400
		export FORCE_NET_MSS=1400
		export LD_PRELOAD=${LD_PRELOAD}:/usr/lib/force_bind.so
		your_program_here

		7. Force bandwidth to 1000 bytes/s for _all_ connections, cumulated
		export FORCE_NET_BW=1000
		export LD_PRELOAD=${LD_PRELOAD}:/usr/lib/force_bind.so
		your_program_here

		8. Force bandwidth to 20000 bytes/s per socket
		export FORCE_NET_BW_PER_SOCKET=20000
		export LD_PRELOAD=${LD_PRELOAD}:/usr/lib/force_bind.so
		scp root@machine1:/image.iso .

		9. Force REUSEADDR
		export FORCE_NET_REUSEADDR=1
		export LD_PRELOAD=${LD_PRELOAD}:/usr/lib/force_bind.so
		your_program_here

		10. Force NODELAY
		export FORCE_NET_NODELAY=1
		export LD_PRELOAD=${LD_PRELOAD}:/usr/lib/force_bind.so
		your_program_here

		11. Force client connections (for example 'telnet', 'ssh',
		'firefox') to connect from a specified address, not the auto
		selected one:
		export FORCE_NET_VERBOSE=1
		export FORCE_BIND_ADDRESS_V4=127.0.0.2
		export LD_PRELOAD=${LD_PRELOAD}:/usr/lib/force_bind.so
		your_program_here

		12. Set a FLOWINFO (flow label + class) for a client connection:
		export FORCE_NET_VERBOSE=1
		export FORCE_NET_FLOWINFO=0x7812345 # class 0x78, label 0x12345
		export LD_PRELOAD=${LD_PRELOAD}:/usr/lib/force_bind.so
		your_program_here
		A tcpdump of a connection will look like:
		00:00:00:00:00:00 > 00:00:00:00:00:00, ethertype IPv6 (0x86dd),
		length 94: (class 0x78, flowlabel 0x12345, hlim 64, next-header TCP (6) payload length: 40)
		::1.56981 > ::1.krb524: Flags [S], cksum 0x0030 (incorrect -> 0x91cf),
		seq 1154252590, win 32752, options [mss 16376,sackOK,TS val 28395104 ecr 0,nop,wscale 4], length 0

		13. Force FWMARK on a connection (only root can do it):
		export FORCE_NET_VERBOSE=1
		export FORCE_NET_FWMARK=0x1234
		export LD_PRELOAD=${LD_PRELOAD}:/usr/lib/force_bind.so
		your_program_here

		14: Force priority (between 0 and 6 for non-root users). You can
		use 'tc' command from iproute to set-up 'prio' qdisc and to
		assign prio to queues:
		# 0. setup
		export FORCE_NET_VERBOSE=1
		export LD_PRELOAD=${LD_PRELOAD}:/usr/lib/force_bind.so
		# 1. Make sure you have a 'prio' qdisc attached to eth0, for example:
		tc qdisc add dev eth0 root handle 1: prio
		# 2. Assign applications to classed (bands):
		export FORCE_NET_PRIO=6 # interactive, band 0
		your_voip_program_here
		export FORCE_NET_PRIO=0 # best effort, band 1
		your_mail_program_here
		export FORCE_NET_PRIO=2 # bulk, band 2
		your_remote_backup_program_here
		# 3. Run tc statistics so you can see the classification:
		tc -s class show dev eth0

		15: Deny binding to any IPv4 sockets. The bind syscall
		will return -1 and errno will be set to EACCES.
		export FORCE_NET_VERBOSE=1
		export FORCE_BIND_ADDRESS_V4=deny
		export LD_PRELOAD=${LD_PRELOAD}:/usr/lib/force_bind.so
		your_program_here

		16: Silent fake binding to any IPv6 sockets. The bind will
		return success, but will never accept any connection.
		export FORCE_NET_VERBOSE=1
		export FORCE_BIND_ADDRESS_V6=fake
		export LD_PRELOAD=${LD_PRELOAD}:/usr/lib/force_bind.so
		your_program_here

Installation:
		- ./configure
		- make
		- make install