Concast Kernel Documentation
Billy Mullins
Overview
Conveniently, the kernel changes are implemented as a loadable module.
You may need to read the Linux HOWTO's on working with modules.
The Concast kernel consists of filters that are implemented using Linux Netfilter.
The filters are controlled via socket options. The socket options exist on multiple levels,
consisting of application options(join, create), and control options(scspd,
rcspd, set flowstate, get flowstate, etc...).
The rest of the documentation assumes you have the knowledge to compile
and install the kernel and modules. If not I recommend the Linux HOWTO's, you can
find them at the
Linux Documentation Project.
Note: This distribution is an old concast release (2001-2002). Although, most of the information is still relevant, the latest release contains many more features. The current concast release including 'Secure Concast', using IPSec channels, is an in-house release that is available only upon request.
Getting Started
To start, you will need a 2.4.X Linux Kernel.
If you already have a concast release distribution from the main
page, the files you need are in the Kernel directory.
Otherwise, download both the
Concast Linux 2.4.X Kernel Patch,
and the
Concast Module Source
and then follow the installation instructions below.
Concast Kernel Setup/Install
-
Assemble the files listed above.
-
Use the patch command to apply the patch to a fresh linux kernel.
If you don't already have a 2.4.X kernel you will need to download
one from Linux Kernel Archives.
-
Untar the Concast Module Source into your freshly patched kernel
directory.
-
Use make xconfig to configure your kernel. For concast you
must enable Linux Netfilter, and enable IPv6 as a module.
-
Once you have configured your kernel run: make depend all modules modules_install
-
While the kernel is compiling edit lilo.conf to contain an entry for
your new Concast kernel. Example:
image=/boot/vmlinuz-2.4.X
label=Concast_v2
Try man lilo, or reference the
Linux Documentation Project.
to learn more about using lilo.
-
You will need to copy the new kernel binary to /boot, you may choose any
name for the new file, but it must correspond to the entry you added to lilo.conf.
The new kernel binary can be found in ./arch/i386/boot/vmlinuz
You will need to:
cp arch/i386/boot/vmlinuz /boot/vmlinuz-2.4.X
Note: Make sure you aren't overwriting a previously installed
2.4.X kernel. Otherwise, if you have not correctly configured your
kernel, you may have difficulty booting your machine. Also, keep
your original kernel as the default.
-
You now need to run lilo, just run it from the command line: lilo
You should see a report such as the following:
# lilo
Added Concast2 *
Added Concast
Added Linux
Added LinuxOLD
#
In this case, Concast2 is the default kernel(selected in lilo.conf), thus
when the machine is rebooted this kernel will be loaded unless the lilo boot
process is interrupted and a new kernel is selected.
At first you will probably want to use your original kernel as the default.
-
Reboot, and select the Concast kernel at the lilo prompt.
-
Once the machine is booted you will need to load the concast module before
you can use its features(ie: run the rcspd, scspd, etc).
If you have been using a kernel version older than 2.4.X, then you will
probably need to get the latest modules utilities package. Otherwise,
you will receive reports indicating the concast module was not found.
To load the concast module use modprobe:
modprobe concast
If you receive error messages indicating missing symbols then your kernel
is not configured correctly. Go back over the kernel configuration process
and make sure you included all the necessary options.
-
Once the module has loaded cleanly you will need to install and
configure the concast signaling daemons(
Concast Signaling Protocol Daemon(CSPd) Distribution).
Kernel Additions
User level control of the concast kernel by the applications, merge daemon,
and signalling daemons is accomplished via socket options(setsockopt,
getsockopt). The list of options is extensive:
Socket Options:
IP_CONCAST_RCSPD
Synopsis:
setsockopt(sk, IPPROTO_IP, IP_CONCAST_RCSPD, (char *)0, 0)
Description:
Setsockopt IP_CONCAST_RCSPD is used to create the RCSPd socket.
There can be only 1 RCSPd socket per node. The RCSPd socket provides unidirectional
communication to the RCSPd from the kernel. Messages of type CONCAST_CREATE
and CONCAST_DESTROY of
the following format are sent on this socket:
| version | type | IP protocol | ...
1 byte 1 byte 1 byte
| receiver address | concast_group_id |
...
4 bytes 4 bytes
| authentication id | original outgoing
source address | ...
4 bytes 4 bytes
wap the above two fields such that:
| original outgoing source address |
authentication id | ...
4 bytes 4 bytes
Also note, the authentication id for a joining sender, is
also the unique sender identification number, thus the
original outgoing source address, and the authentication id
make up the sender id that is transmitted as part of
the concast option.
| mspec length | credentials length |
...
4 bytes 4 bytes
| merge spec | credential |
mspec length bytes credentials length
bytes
IP_CONCAST_SCSPD:
Synopsis:
setsockopt(sk, IPPROTO_IP, IP_CONCAST_SCSPD, (char *)0, 0)
Description:
Setsockopt IP_CONCAST_SCSPD is used to
create the SCSPd socket. There can be only 1 SCSPd socket per
node. The SCSPd socket provides unidirectional communication
to the SCSPd from the kernel. Messages of type CONCAST_LEAVE
and CONCAST_JOIN of with the same format as messages to the
RCSPd. Messages received on this socket are the same format as
message received on the RCSPd socket.
IP_CONCAST_JOIN:
Uses Structures:
struct concast_flowspec fspec
or
struct concast_secure_flowspec sfspec
Synopsis:
setsockopt(sk, IPPROTO_IP,
IP_CONCAST_JOIN, (char *)&fspec, sizeof(fspec
or
setsockopt(sk, IPPROTO_IP,
IP_CONCAST_JOIN, (char *)&sfspec, sizeof(sfsp
c))
Description:
Setsockopt IP_CONCAST_JOIN is used to attach senders to a flow.
The receiver address, and concast group id fields of the flow
spec must be set for basic concast. For secure concast, credentials
to be verified by the cspd must set using the cred_length, and cred
fields of the secure flowspec. IP_CONCAST_JOIN will block waiting on
credential verification, and also on the flow state to change from
PENDING, if it was PENDING at the time of the call.
A message will be passed to the local SCSPd on the SCSPd socket, at which point, in the case of
authentication or protocol verification, the caller will be blocked until the
SCSPd, has given IP_CONCAST_AUTH, o IP_CONCAST_NOAUTH. If the sender was
not authenticated the call will return with an error. The CSPd is
also responsible for changing the flowstate from PENDING, at
which point the sender can begin to send on the concast flow.
IP_CONCAST_CREATE:
Uses Structures:
struct concast_mergespec mspec
or
struct concast_secure_mergespec smspec
Synopsis:
setsockopt(sk, IPPROTO_IP,
IP_CONCAST_CREATE, (char *)&mspec, sizeof(mspec))
setsockopt(sk, IPPROTO_IP,
IP_CONCAST_CREATE, (char *)&smspec, sizeof(smpec))
Description:
Setsockopt IP_CONCAST_CREATE is used to initiate a concast flow.
The receiver address, and concast group id fields of the flow
spec must be set for basic concast. For secure concast, the credentials
to be verified by the CSPd must set in the security credential fields
of the secure merge spec. The concast merge spec structure
also contains the length and a pointer to the merge spec. The
merge spec will be passed to the RCSPd on the RCSPd socket.
The protocol of the IP_CONCAST_CREATE socket will be the protocol of
the flow. The SCSPds should during the acceptance of the request to join the flow,
verify that the joining sender is using the same protocol as the receiver.
IP_CONCAST_CREATE will block waiting on credential verification by
the CSPd. A message will be passed to the local RCSPd on the RCSPd socket,
at which point, in the case of authentication the caller will be
blocked until the RCSPd, has given IP_CONCAST_AUTH, or
IP_CONCAST_NOAUTH. If the receiver was not authenticated the call
will return with an error.
IP_CONCAST_CONTROL:
Uses Structures:
struct concast_control_msg cmsg
Synopsis:
setsockopt(sk, IPPROTO_IP, IP_CONCAST_CONTROL, (char *)&cmsg, sizeof(cmsg))
Description:
Used by concast receivers to pass control messages to the local RCSPd. The protocol
format of the control messages is defined by the RCSPd. The messages are not
parsed/processed within the kernel.
Can be called only by a concast receiver (created via IP_CONCAST_CREATE), therefore
sk must be the socket associated with the flow to which the message corresponds.
IP_CONCAST_MERGE
Uses Structures:
struct concast_flowspec fspec
Synopsis:
setsockopt(sk, IPPROTO_IP, IP_CONCAST_MERGE, (char *)&fspec, sizeof(fspec))
Description:
Setsockopt IP_CONCAST_MERGE should be called by RCSPd's to create a sock
t to be used by the merged when it is forked. MERGEd sockets may only
be AF_INET RAW sockets, and the protocol should match the protocol of th
flow. For instance if the flow was a UDP flow the flow should be
created with: sk = socket(AF_INET, SOCK_RAW, IPPROTO_UDP). The data received on
the MERGEd socket will include the ip header and options, while the data transmitted
should only be the transport header and up. Data will not be received on the MERGEd
socket, unless the flow has been set to FLOW_STATE_MERGING using
setsockopt IP_CONCAST_FSTATE.
IP_CONCAST_FSTATE
Uses Structures:
struct concast_flowstate fstate
Synopsis:
setsockopt(sk, IPPROTO_IP, IP_CONCAST_FSTATE, (char *)&fspec, sizeof(fspec))
getsockopt(sk, IPPROTO_IP, IP_CONCAST_FSTATE, (char *)&fspec, &sizeof(fspec))
Description(set):
Given a filled in flow state structure the kernel will set the
state, and wake up any sender processes waiting on the state
to change from pending.
Description(get):
Given a flow state structure with the flow spec set, the flow
state structure is completed.
IP_CONCAST_AUTH
Uses Structures:
struct concast_security_authentication csa;
Synopsis:
setsockopt(sk, IPPROTO_IP, IP_CONCAST_AUTH, (char *)&csa, sizeof(csa));
Description:
When a flow is using authentication the CSPd is required to
authenticate sender, and receivers, before their respective
calls to create concast sockets will return. The calls are
blocked until the authentication credentials are verified
by the CSPD, and the CSPD makes the IP_CONCAST_AUTH
call. The authentication id field of the csa is used
to identify the entity that is to be authenticated. The
id is given to the CSPD via the CSPD socket.
IP_CONCAST_NOAUTH
Uses Structures:
struct concast_security_authentication csa;
Synopsis:
setsockopt(sk, IPPROTO_IP, IP_CONCAST_AUTH, (char *)&csa, sizeof(csa));
Description:
To deny authentication the IP_CONCAST_NOAUTH call is used.
When this call is made the entity with the given authentication
id will return from the blocked call with an error of EPERM.
Structures:
struct concast_control_msg {
unsigned int msg_length;
char *ptr_to_msg;
};
struct concast_security_credential {
unsigned int cred_length;
char *ptr_to_cred;
};
/* Flow specification for concast. */
struct concast_flowspec {
unsigned int recvaddr; /* IP concast receiver address. */
unsigned int concast_group_id; /* application id. */
};
struct concast_flowstate_request {
struct concast_flowspec fspec;
unsigned int state;
};
struct concast_secure_flowspec {
struct concast_flowspec fspec;
struct concast_security_credential
scred;
};
struct concast_security_authentication {
struct concast_flowspec fspec;
unsigned int auth_id;
};
/* Merge specification for concast create call. */
struct concast_mergespec {
struct concast_flowspec fspec;
unsigned int mspec_length;
char *ptr_to_mspec;
};
struct concast_secure_mergespec {
struct concast_mergespec mspec;
struct concast_security_credential scred;
};
We have also composed a text file of the potential errors from calls to
the system calls or to setsockopt using the concast options. You
may need to look at the code to see exactly what is causing the
error, but this file will save you some time.
(Error Tracking Info).
For examples of use, you should look at the user level daemon and the application code.
The base(simplest) examples are included in the Test directories of the Concast user
level source distribution, and can be used as a starting point for building concast
applications.
Debugging
If you run into problems, or are further interested in the kernel
functionality with respect to the applications, the concast module
may be loaded with a debug flag. Doing so will allow different
levels of debugging information to be displayed.
Debugging may be turned on in levels 1-N. To turn on debugging with
the module the parameter cdebug needs to be be set as follows:
modprobe concast cdebug=1
If you are not compiling concast as a modules you'll need to set
the value of cdebug at compile time.
If you need further assistance with the kernel you may send mail to
