You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Patrick J Cherry 885990c5b3 Updated changelog 4 years ago
debian Updated changelog 4 years ago
examples Reorganise under Linux:: 9 years ago
lib/linux Updated linux header constants 4 years ago
test Scaled back the massive allocation of IPs from 11 /24s to 4. 5 years ago
.gitignore Initial commit, work in progress 9 years ago
.hgignore Added patches to remove rubygems requirements. 7 years ago
README Added working NLSocket.open and scope handling. 9 years ago
Rakefile Removed need for gcc as a dependency for debian packages. 8 years ago
netlinkrb.gemspec Updated to 0.18 4 years ago

README

Ruby Netlink
============

This library provides an API for using a Linux Netlink socket, for doing
things like manipulating IP interfaces and routes programmatically, and
capturing packets from ULOG.

Example
=======

require 'linux/netlink/route'
ip = Linux::Netlink::Route::Socket.new

# Info about eth0 interface
p ip.link["eth0"]

# Addresses on eth0 interface
ip.addr.list(:index=>"eth0") do |addr|
puts addr.address
end

See the examples/ and test/ directories for more examples.

Requirements
============

ruby 1.9 (tested with ruby 1.9.2), OR ruby 1.8.7 with the ffi library.

Code organisation
=================

There are separate classes for each Netlink protocol providing a high-level
API. These all in turn use the NLSocket class, which has methods for adding
the headers to messages and sending them over a socket. The messages
themselves are built using class Message or RtattrMessage, which in turn are
subclasses of CStruct, which performs the low-level packing and unpacking of
the message bodies.

LinkHandler/
AddrHandler/
VlanHandler/
RouteHandler
|
v
Route Firewall NFLog ...etc
| | |
+-------+-------+
|
v
NLSocket
|
v
Message / RtattrMessage
|
v
CStruct

Useful reference material
=========================

* http://www.linuxjournal.com/article/7356
* http://people.redhat.com/nhorman/papers/netlink.pdf
* apt-get source iproute

Note there are some errors in the nhorman paper. On page 8/9, it says

nlmsg_pid ... Also note that it is
imperative that any program receiving netlink socket messages from
the kernel verify that this field is set to zero, or it is possible to expose
the software to unexpected influences from other non-privlidged user
space programs.

However, what really needs to be checked is the pid in the sockaddr_nl
structure returned by recvmsg msghdr, as shown by this code in
lib/libnetlink.c:

struct msghdr msg = {
.msg_name = &nladdr,
.msg_namelen = sizeof(nladdr),
.msg_iov = &iov,
.msg_iovlen = 1,
};
...
status = recvmsg(rth->fd, &msg, 0);
...
if (nladdr.nl_pid != 0 ||
h->nlmsg_pid != rth->local.nl_pid ||
h->nlmsg_seq != rth->dump) {

TODO
====

* Exception hierarchy
* More tests
* More netlink protocols

Copyright
=========
(C) 2011 Bytemark Hosting
Written by Brian Candler <B.Candler@pobox.com>

Distribute under the same terms as Ruby
http://www.ruby-lang.org/en/LICENSE.txt