README.txt in netcheck – Netcheck

Line
1	This is a brief overview of what all the different modules do and how
2	they work together. In order to run NetCheck, you need to write a
3	configuration file in order to tell NetCheck where to find the trace
4	files and how the network is configured. Consult example_config.txt for
5	information on how to write configuration files. Traces can then be
6	verified by running: python trace_ordering.py CONFIGURATION_FILE
7
8
9
10	lind_fs_constants / lind_net_constants
11	------------------------------------------------------------------------
12	Defines a lot of constants used by posix_test_harness_functions.
13
14
15	posix_test_harness_functions
16	------------------------------------------------------------------------
17	Reads in strace output file and returns tuples for system calls that can
18	affect the network or open file descriptors. Responsible for converting
19	strace output into easily usable data structures. Can be used either to
20	read the next system call from a file or to read in the entire trace.
21
22
23	posix_preprocessor
24	------------------------------------------------------------------------
25	Uses generators to wrap the output of posix_test_harness_functions. This
26	means that the returned "traces" are actually reading and parsing lines
27	as they are needed instead of trying to read the entire trace into
28	memory. The module also has a preprocessor that tracks which file
29	descriptors are duplicates of each other and outputs a "trace" (again,
30	actually a generator) with the property that each socket is uniquely
31	indentified by a single file descriptor. Calls like clone and dup are
32	stripped from the trace since they are already handled by the
33	preprocessor, and close calls are removed if they close a duplicate
34	file descriptor and not the actually socket.
35
36
37	ipaddr
38	------------------------------------------------------------------------
39	A library we are using for processing IPv4 and IPv6 addresses. Taken
40	from http://code.google.com/p/ipaddr-py/.
41
42
43	ip_matching
44	------------------------------------------------------------------------
45	Handles loading traces from configuration files and comparing addresses
46	based on the network configuration defined by the configuration file.
47	As part of this matching, it also identifies properties of possible
48	connections that the user should be aware of, like traversing a NAT,
49	connecting to 0.0.0.0, or connecting to an IPv6 address from an IPv4
50	address. Uses ipaddr extensively for indentifying properties of IP
51	addresses and uses posix_preprocessor to load preprocessed trace files.
52
53
54	model_network_syscalls
55	------------------------------------------------------------------------
56	This is where most of the actually processing occurs. Contains funtions
57	for all the network related systems calls that we care about and
58	simulates the results of invoking the system calls based on the current
59	model state. Uses ip_matching to determine which socket pairs
60	correspond to network connections.
61
62
63	posix_ordering
64	------------------------------------------------------------------------
65	Used to run configuration files. Takes the name of a configuration file
66	as its only argument and feeds this name into ip_matching to initialize
67	the network configuration and get back a list of traces to verify. Then
68	the module uses trace_ordering to perform the ordering.
69	Uses posix_output for logging results.
70
71
72	posix_output
73	------------------------------------------------------------------------
74	This is where I've been moving all the logging functionality from
75	posix_ordering. It also now handles generating some statistic and
76	warnings based on the exceptions raised by the model over the course of
77	its execution and the final state of the model.
78
79
80	trace_ordering
81	------------------------------------------------------------------------
82	Used to order traces. This and trace_output are the two non posix
83	specific files. Uses trace_output for logging results.
84
85
86	trace_output
87	------------------------------------------------------------------------
88	Contains a number of useful function for logging ordering results.
89