STRLCPY/ebpfguard

Add docs and README
Michal Rostecki committed with vadorovsky 1 year ago

14d32854

1 parent ece1efec

■ ■ ■ ■ ■ ■

LICENSE

1	+	Apache License
2	+	Version 2.0, January 2004
3	+	http://www.apache.org/licenses/
4	+
5	+	TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6	+
7	+	1. Definitions.
8	+
9	+	"License" shall mean the terms and conditions for use, reproduction,
10	+	and distribution as defined by Sections 1 through 9 of this document.
11	+
12	+	"Licensor" shall mean the copyright owner or entity authorized by
13	+	the copyright owner that is granting the License.
14	+
15	+	"Legal Entity" shall mean the union of the acting entity and all
16	+	other entities that control, are controlled by, or are under common
17	+	control with that entity. For the purposes of this definition,
18	+	"control" means (i) the power, direct or indirect, to cause the
19	+	direction or management of such entity, whether by contract or
20	+	otherwise, or (ii) ownership of fifty percent (50%) or more of the
21	+	outstanding shares, or (iii) beneficial ownership of such entity.
22	+
23	+	"You" (or "Your") shall mean an individual or Legal Entity
24	+	exercising permissions granted by this License.
25	+
26	+	"Source" form shall mean the preferred form for making modifications,
27	+	including but not limited to software source code, documentation
28	+	source, and configuration files.
29	+
30	+	"Object" form shall mean any form resulting from mechanical
31	+	transformation or translation of a Source form, including but
32	+	not limited to compiled object code, generated documentation,
33	+	and conversions to other media types.
34	+
35	+	"Work" shall mean the work of authorship, whether in Source or
36	+	Object form, made available under the License, as indicated by a
37	+	copyright notice that is included in or attached to the work
38	+	(an example is provided in the Appendix below).
39	+
40	+	"Derivative Works" shall mean any work, whether in Source or Object
41	+	form, that is based on (or derived from) the Work and for which the
42	+	editorial revisions, annotations, elaborations, or other modifications
43	+	represent, as a whole, an original work of authorship. For the purposes
44	+	of this License, Derivative Works shall not include works that remain
45	+	separable from, or merely link (or bind by name) to the interfaces of,
46	+	the Work and Derivative Works thereof.
47	+
48	+	"Contribution" shall mean any work of authorship, including
49	+	the original version of the Work and any modifications or additions
50	+	to that Work or Derivative Works thereof, that is intentionally
51	+	submitted to Licensor for inclusion in the Work by the copyright owner
52	+	or by an individual or Legal Entity authorized to submit on behalf of
53	+	the copyright owner. For the purposes of this definition, "submitted"
54	+	means any form of electronic, verbal, or written communication sent
55	+	to the Licensor or its representatives, including but not limited to
56	+	communication on electronic mailing lists, source code control systems,
57	+	and issue tracking systems that are managed by, or on behalf of, the
58	+	Licensor for the purpose of discussing and improving the Work, but
59	+	excluding communication that is conspicuously marked or otherwise
60	+	designated in writing by the copyright owner as "Not a Contribution."
61	+
62	+	"Contributor" shall mean Licensor and any individual or Legal Entity
63	+	on behalf of whom a Contribution has been received by Licensor and
64	+	subsequently incorporated within the Work.
65	+
66	+	2. Grant of Copyright License. Subject to the terms and conditions of
67	+	this License, each Contributor hereby grants to You a perpetual,
68	+	worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69	+	copyright license to reproduce, prepare Derivative Works of,
70	+	publicly display, publicly perform, sublicense, and distribute the
71	+	Work and such Derivative Works in Source or Object form.
72	+
73	+	3. Grant of Patent License. Subject to the terms and conditions of
74	+	this License, each Contributor hereby grants to You a perpetual,
75	+	worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76	+	(except as stated in this section) patent license to make, have made,
77	+	use, offer to sell, sell, import, and otherwise transfer the Work,
78	+	where such license applies only to those patent claims licensable
79	+	by such Contributor that are necessarily infringed by their
80	+	Contribution(s) alone or by combination of their Contribution(s)
81	+	with the Work to which such Contribution(s) was submitted. If You
82	+	institute patent litigation against any entity (including a
83	+	cross-claim or counterclaim in a lawsuit) alleging that the Work
84	+	or a Contribution incorporated within the Work constitutes direct
85	+	or contributory patent infringement, then any patent licenses
86	+	granted to You under this License for that Work shall terminate
87	+	as of the date such litigation is filed.
88	+
89	+	4. Redistribution. You may reproduce and distribute copies of the
90	+	Work or Derivative Works thereof in any medium, with or without
91	+	modifications, and in Source or Object form, provided that You
92	+	meet the following conditions:
93	+
94	+	(a) You must give any other recipients of the Work or
95	+	Derivative Works a copy of this License; and
96	+
97	+	(b) You must cause any modified files to carry prominent notices
98	+	stating that You changed the files; and
99	+
100	+	(c) You must retain, in the Source form of any Derivative Works
101	+	that You distribute, all copyright, patent, trademark, and
102	+	attribution notices from the Source form of the Work,
103	+	excluding those notices that do not pertain to any part of
104	+	the Derivative Works; and
105	+
106	+	(d) If the Work includes a "NOTICE" text file as part of its
107	+	distribution, then any Derivative Works that You distribute must
108	+	include a readable copy of the attribution notices contained
109	+	within such NOTICE file, excluding those notices that do not
110	+	pertain to any part of the Derivative Works, in at least one
111	+	of the following places: within a NOTICE text file distributed
112	+	as part of the Derivative Works; within the Source form or
113	+	documentation, if provided along with the Derivative Works; or,
114	+	within a display generated by the Derivative Works, if and
115	+	wherever such third-party notices normally appear. The contents
116	+	of the NOTICE file are for informational purposes only and
117	+	do not modify the License. You may add Your own attribution
118	+	notices within Derivative Works that You distribute, alongside
119	+	or as an addendum to the NOTICE text from the Work, provided
120	+	that such additional attribution notices cannot be construed
121	+	as modifying the License.
122	+
123	+	You may add Your own copyright statement to Your modifications and
124	+	may provide additional or different license terms and conditions
125	+	for use, reproduction, or distribution of Your modifications, or
126	+	for any such Derivative Works as a whole, provided Your use,
127	+	reproduction, and distribution of the Work otherwise complies with
128	+	the conditions stated in this License.
129	+
130	+	5. Submission of Contributions. Unless You explicitly state otherwise,
131	+	any Contribution intentionally submitted for inclusion in the Work
132	+	by You to the Licensor shall be under the terms and conditions of
133	+	this License, without any additional terms or conditions.
134	+	Notwithstanding the above, nothing herein shall supersede or modify
135	+	the terms of any separate license agreement you may have executed
136	+	with Licensor regarding such Contributions.
137	+
138	+	6. Trademarks. This License does not grant permission to use the trade
139	+	names, trademarks, service marks, or product names of the Licensor,
140	+	except as required for reasonable and customary use in describing the
141	+	origin of the Work and reproducing the content of the NOTICE file.
142	+
143	+	7. Disclaimer of Warranty. Unless required by applicable law or
144	+	agreed to in writing, Licensor provides the Work (and each
145	+	Contributor provides its Contributions) on an "AS IS" BASIS,
146	+	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147	+	implied, including, without limitation, any warranties or conditions
148	+	of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149	+	PARTICULAR PURPOSE. You are solely responsible for determining the
150	+	appropriateness of using or redistributing the Work and assume any
151	+	risks associated with Your exercise of permissions under this License.
152	+
153	+	8. Limitation of Liability. In no event and under no legal theory,
154	+	whether in tort (including negligence), contract, or otherwise,
155	+	unless required by applicable law (such as deliberate and grossly
156	+	negligent acts) or agreed to in writing, shall any Contributor be
157	+	liable to You for damages, including any direct, indirect, special,
158	+	incidental, or consequential damages of any character arising as a
159	+	result of this License or out of the use or inability to use the
160	+	Work (including but not limited to damages for loss of goodwill,
161	+	work stoppage, computer failure or malfunction, or any and all
162	+	other commercial damages or losses), even if such Contributor
163	+	has been advised of the possibility of such damages.
164	+
165	+	9. Accepting Warranty or Additional Liability. While redistributing
166	+	the Work or Derivative Works thereof, You may choose to offer,
167	+	and charge a fee for, acceptance of support, warranty, indemnity,
168	+	or other liability obligations and/or rights consistent with this
169	+	License. However, in accepting such obligations, You may act only
170	+	on Your own behalf and on Your sole responsibility, not on behalf
171	+	of any other Contributor, and only if You agree to indemnify,
172	+	defend, and hold each Contributor harmless for any liability
173	+	incurred by, or claims asserted against, such Contributor by reason
174	+	of your accepting any such warranty or additional liability.
175	+
176	+	END OF TERMS AND CONDITIONS
177	+
178	+	APPENDIX: How to apply the Apache License to your work.
179	+
180	+	To apply the Apache License to your work, attach the following
181	+	boilerplate notice, with the fields enclosed by brackets "[]"
182	+	replaced with your own identifying information. (Don't include
183	+	the brackets!) The text should be enclosed in the appropriate
184	+	comment syntax for the file format. We also recommend that a
185	+	file or class name and description of purpose be included on the
186	+	same "printed page" as the copyright notice for easier
187	+	identification within third-party archives.
188	+
189	+	Copyright [yyyy] [name of copyright owner]
190	+
191	+	Licensed under the Apache License, Version 2.0 (the "License");
192	+	you may not use this file except in compliance with the License.
193	+	You may obtain a copy of the License at
194	+
195	+	http://www.apache.org/licenses/LICENSE-2.0
196	+
197	+	Unless required by applicable law or agreed to in writing, software
198	+	distributed under the License is distributed on an "AS IS" BASIS,
199	+	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200	+	See the License for the specific language governing permissions and
201	+	limitations under the License.
202	+

■ ■ ■ ■ ■ ■

README.md

1	1		# guardity
2	2
	3	+	Guardity is a library for managing Linux security policies. It is based on
	4	+	[LSM hooks](https://www.kernel.org/doc/html/latest/admin-guide/LSM/index.html),
	5	+	but without necessity to write any kernel modules or eBPF programs directly.
	6	+	It allows to write policies in Rust (or YAML) in user space.
	7	+
	8	+	It's based on eBPF and [Aya](https://aya-rs.dev) library, but takes away
	9	+	the need to use them directly.
	10	+
3	11		## Prerequisites
4	12
5		-	1. Install a rust stable toolchain: `rustup install stable`
6		-	1. Install a rust nightly toolchain with the rust-src component: `rustup toolchain install nightly --component rust-src`
7		-	1. Install bpf-linker: `cargo install bpf-linker`
	13	+	First, you need to have a Linux kernel:
	14	+	* with BTF support
	15	+	* with BPF LSM support (kernels >= 5.7)
8	16
9		-	## Build eBPF
	17	+	You can check if your kernel has BTF support by checking whether file
	18	+	`/sys/kernel/btf/vmlinux` exists. You can also check the kernel configuration:
10	19
11	20		```bash
12		-	cargo xtask build-ebpf
	21	+	$ zgrep CONFIG_DEBUG_INFO_BTF /proc/config.gz
	22	+	CONFIG_DEBUG_INFO_BTF=y
13	23		```
14	24
15		-	To perform a release build you can use the `--release` flag.
16		-	You may also change the target architecture with the `--target` flag.
	25	+	Next, you need to check if your kernel has BPF LSM support:
	26	+
	27	+	```bash
	28	+	$ cat /sys/kernel/security/lsm
	29	+	lockdown,capability,selinux,bpf
	30	+	```
	31	+
	32	+	If the output doesn't contain `bpf`, you need to enable BPF LSM by adding
	33	+	`lsm=[...],bpf` to your kernel config parameters. That can be achieved by
	34	+	executing the [following script](https://raw.githubusercontent.com/vadorovsky/enable-bpf-lsm/main/enable-bpf-lsm.py).
	35	+
	36	+	Then you need the Rust stable and nightly toolchains installed on your system,
	37	+	as well as bpf-linker. You can install these by following these
	38	+	[instructions](https://aya-rs.dev/book/start/development/).
	39	+
	40	+	## LSM hooks
	41	+
	42	+	LSM hooks supported by Guardity are:
	43	+
	44	+	* [`bprm_check_security`](https://elixir.bootlin.com/linux/v6.2.12/source/include/linux/lsm_hooks.h#L62)
	45	+	* [`file_open`](https://elixir.bootlin.com/linux/v6.2.12/source/include/linux/lsm_hooks.h#L620)
	46	+	* [`task_fix_setuid`](https://elixir.bootlin.com/linux/v6.2.12/source/include/linux/lsm_hooks.h#L709)
	47	+	* [`socket_bind`](https://elixir.bootlin.com/linux/v6.2.12/source/include/linux/lsm_hooks.h#L904)
	48	+	* [`socket_connect`](https://elixir.bootlin.com/linux/v6.2.12/source/include/linux/lsm_hooks.h#L912)
	49	+
	50	+	## Examples
	51	+
	52	+	### Defining single policies
17	53
18		-	## Build Userspace
	54	+	The [file_open](https://github.com/deepfence/guardity/tree/main/examples/file_open)
	55	+	example shows how to define a policy for `file_open` LSM hook as Rust code.
	56	+	It denies the given binary (or all processes, if none defined) from opening
	57	+	the given directory.
	58	+
	59	+	To try it out, let's create a directory and a file inside it:
19	60
20	61		```bash
21		-	cargo build
	62	+	$ mkdir /tmp/test
	63	+	$ echo "foo" > /tmp/test/test
	64	+	```
	65	+
	66	+	Then run our example policy program with:
	67	+
	68	+	```rust
	69	+	$ RUST_LOG=info cargo xtask run --example file_open -- --path-to-deny /tmp/test
	70	+	```
	71	+
	72	+	When trying to access that directory and file, you should see that these
	73	+	operations are denied:
	74	+
	75	+	```bash
	76	+	$ ls /tmp/test/
	77	+	ls: cannot open directory '/tmp/test/': Operation not permitted
	78	+	$ cat /tmp/test/test
	79	+	cat: /tmp/test/test: Operation not permitted
	80	+	```
	81	+
	82	+	The policy application should show logs like:
	83	+
	84	+	```rust
	85	+	[2023-04-22T20:51:01Z INFO file_open] file_open: pid=3001 subject=980333 path=9632
	86	+	[2023-04-22T20:51:03Z INFO file_open] file_open: pid=3010 subject=980298 path=9633
	87	+	```
	88	+
	89	+	### Daemon with CLI and YAML engine
	90	+
	91	+	Run the daemon with:
	92	+
	93	+	```bash
	94	+	$ RUST_LOG=info cargo xtask run --example daemon
	95	+	```
	96	+
	97	+	Then manage the policies using the CLI:
	98	+
	99	+	```bash
	100	+	$ cargo xtask run --example cli -- --help
22	101		```
23	102
24		-	## Run
	103	+	You can apply policies from the
	104	+	[example YAML file](https://github.com/deepfence/guardity/blob/main/examples/cli/policy.yaml):
25	105
26	106		```bash
27		-	RUST_LOG=info cargo xtask run
	107	+	$ cargo xtask run --example cli -- policy add --path examples/cli/policy.yaml
28	108		```
29	109
	110	+	## License
	111	+
	112	+	Guardity's userspace part is licensed under
	113	+	[Apache License, version 2.0](https://github.com/deepfence/guardity/blob/main/LICENSE).
	114	+
	115	+	eBPF programs inside guardity-ebpf directory are licensed under
	116	+	[GNU General Public License, version 2](https://github.com/deepfence/guardity/blob/main/guardity-ebpf/LICENSE).
	117	+

■ ■ ■ ■ ■ ■

policy.yaml examples/cli/policy.yaml

		skipped 7 lines
8	8		subject: all
9	9		allow: all
10	10		deny: !paths
11		-	- /home/vadorovsky/forbidden
	11	+	- /tmp/test
12	12		- !socket_bind
13	13		subject: all
14	14		allow: !ports
		skipped 9 lines

■ ■ ■ ■ ■ ■

guardity/src/lib.rs

	1	+	//! Guardity is a library for managing Linux security policies. It is based on
	2	+	//! [LSM hooks](https://www.kernel.org/doc/html/latest/admin-guide/LSM/index.html),
	3	+	//! but without necessity to write any kernel modules or eBPF programs directly.
	4	+	//! It allows to write policies in Rust (or YAML) in user space.
	5	+	//!
	6	+	//! It's based on eBPF and [Aya](https://aya-rs.dev) library, but takes away
	7	+	//! the need to use them directly.
	8	+	//!
	9	+	//! # Prerequisites
	10	+	//!
	11	+	//! First, you need to have a Linux kernel:
	12	+	//! * with BTF support
	13	+	//! * with BPF LSM support (kernels >= 5.7)
	14	+	//!
	15	+	//! You can check if your kernel has BTF support by checking whether file
	16	+	//! `/sys/kernel/btf/vmlinux` exists. You can also check the kernel configuration:
	17	+	//!
	18	+	//! ```bash
	19	+	//! $ zgrep CONFIG_DEBUG_INFO_BTF /proc/config.gz
	20	+	//! CONFIG_DEBUG_INFO_BTF=y
	21	+	//! ```
	22	+	//!
	23	+	//! Next, you need to check if your kernel has BPF LSM support:
	24	+	//!
	25	+	//! ```bash
	26	+	//! $ cat /sys/kernel/security/lsm
	27	+	//! lockdown,capability,selinux,bpf
	28	+	//! ```
	29	+	//!
	30	+	//! If the output doesn't contain `bpf`, you need to enable BPF LSM by adding
	31	+	//! `lsm=[...],bpf` to your kernel config parameters. That can be achieved by
	32	+	//! executing the [following script](https://raw.githubusercontent.com/vadorovsky/enable-bpf-lsm/main/enable-bpf-lsm.py).
	33	+	//!
	34	+	//! Then you need the Rust stable and nightly toolchains installed on your system,
	35	+	//! as well as bpf-linker. You can install these by following these
	36	+	//! [instructions](https://aya-rs.dev/book/start/development/).
	37	+	//!
	38	+	//! # LSM hooks
	39	+	//!
	40	+	//! LSM hooks supported by Guardity are:
	41	+	//!
	42	+	//! * [`bprm_check_security`](https://elixir.bootlin.com/linux/v6.2.12/source/include/linux/lsm_hooks.h#L62)
	43	+	//! * [`file_open`](https://elixir.bootlin.com/linux/v6.2.12/source/include/linux/lsm_hooks.h#L620)
	44	+	//! * [`task_fix_setuid`](https://elixir.bootlin.com/linux/v6.2.12/source/include/linux/lsm_hooks.h#L709)
	45	+	//! * [`socket_bind`](https://elixir.bootlin.com/linux/v6.2.12/source/include/linux/lsm_hooks.h#L904)
	46	+	//! * [`socket_connect`](https://elixir.bootlin.com/linux/v6.2.12/source/include/linux/lsm_hooks.h#L912)
	47	+	//!
	48	+	//! # Examples
	49	+	//!
	50	+	//! ## Defining single policies
	51	+	//!
	52	+	//! The [file_open](https://github.com/deepfence/guardity/tree/main/examples/file_open)
	53	+	//! example shows how to define a policy for `file_open` LSM hook as Rust code.
	54	+	//! It denies the given binary (or all processes, if none defined) from opening
	55	+	//! the given directory.
	56	+	//!
	57	+	//! To try it out, let's create a directory and a file inside it:
	58	+	//!
	59	+	//! ```bash
	60	+	//! $ mkdir /tmp/test
	61	+	//! $ echo "foo" > /tmp/test/test
	62	+	//! ```
	63	+	//!
	64	+	//! Then run our example policy program with:
	65	+	//!
	66	+	//! ```
	67	+	//! $ RUST_LOG=info cargo xtask run --example file_open -- --path-to-deny /tmp/test
	68	+	//! ```
	69	+	//!
	70	+	//! When trying to access that directory and file, you should see that these
	71	+	//! operations are denied:
	72	+	//!
	73	+	//! ```bash
	74	+	//! $ ls /tmp/test/
	75	+	//! ls: cannot open directory '/tmp/test/': Operation not permitted
	76	+	//! $ cat /tmp/test/test
	77	+	//! cat: /tmp/test/test: Operation not permitted
	78	+	//! ```
	79	+	//!
	80	+	//! The policy application should show logs like:
	81	+	//!
	82	+	//! ```
	83	+	//! [2023-04-22T20:51:01Z INFO file_open] file_open: pid=3001 subject=980333 path=9632
	84	+	//! [2023-04-22T20:51:03Z INFO file_open] file_open: pid=3010 subject=980298 path=9633
	85	+	//! ```
	86	+	//!
	87	+	//! ## Daemon with CLI and YAML engine
	88	+	//!
	89	+	//! Run the daemon with:
	90	+	//!
	91	+	//! ```bash
	92	+	//! $ RUST_LOG=info cargo xtask run --example daemon
	93	+	//! ```
	94	+	//!
	95	+	//! Then manage the policies using the CLI:
	96	+	//!
	97	+	//! ```bash
	98	+	//! $ cargo xtask run --example cli -- --help
	99	+	//! ```
	100	+	//!
	101	+	//! You can apply policies from the
	102	+	//! [example YAML file](https://github.com/deepfence/guardity/blob/main/examples/cli/policy.yaml):
	103	+	//!
	104	+	//! ```bash
	105	+	//! $ cargo xtask run --example cli -- policy add --path examples/cli/policy.yaml
	106	+	//! ```
	107	+	//!
	108	+	//! # License
	109	+	//!
	110	+	//! Guardity's userspace part is licensed under
	111	+	//! [Apache License, version 2.0](https://github.com/deepfence/guardity/blob/main/LICENSE).
	112	+	//!
	113	+	//! eBPF programs inside guardity-ebpf directory are licensed under
	114	+	//! [GNU General Public License, version 2](https://github.com/deepfence/guardity/blob/main/guardity-ebpf/LICENSE).
	115	+
1	116		use std::path::Path;
2	117
3	118		use aya::{
		skipped 15 lines
19	134		}
20	135
21	136		impl PolicyManager {
	137	+	/// Creates a new policy manager.
	138	+	///
	139	+	/// # Example
	140	+	///
	141	+	/// ```rust
	142	+	/// use guardity::PolicyManager;
	143	+	/// use std::path::Path;
	144	+	///
	145	+	/// let mut policy_manager = PolicyManager::new(Path::new("/sys/fs/bpf/mypolicies")).unwrap();
	146	+	/// ```
22	147		pub fn new<P: AsRef<Path>>(bpf_path: P) -> anyhow::Result<Self> {
23	148		#[cfg(debug_assertions)]
24	149		let bpf = BpfLoader::new()
		skipped 11 lines
36	161		Ok(Self { bpf })
37	162		}
38	163
	164	+	/// Attaches and returns a handle to all LSM hooks.
39	165		pub fn attach_all(&mut self) -> anyhow::Result<All> {
40	166		let bprm_check_security = self.attach_bprm_check_security()?;
41	167		let file_open = self.attach_file_open()?;
		skipped 189 lines

■ ■ ■ ■ ■ ■

guardity-ebpf/LICENSE

1	+
2	+	GNU GENERAL PUBLIC LICENSE
3	+	Version 2, June 1991
4	+
5	+	Copyright (C) 1989, 1991 Free Software Foundation, Inc.
6	+	51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
7	+	Everyone is permitted to copy and distribute verbatim copies
8	+	of this license document, but changing it is not allowed.
9	+
10	+	Preamble
11	+
12	+	The licenses for most software are designed to take away your
13	+	freedom to share and change it. By contrast, the GNU General Public
14	+	License is intended to guarantee your freedom to share and change free
15	+	software--to make sure the software is free for all its users. This
16	+	General Public License applies to most of the Free Software
17	+	Foundation's software and to any other program whose authors commit to
18	+	using it. (Some other Free Software Foundation software is covered by
19	+	the GNU Library General Public License instead.) You can apply it to
20	+	your programs, too.
21	+
22	+	When we speak of free software, we are referring to freedom, not
23	+	price. Our General Public Licenses are designed to make sure that you
24	+	have the freedom to distribute copies of free software (and charge for
25	+	this service if you wish), that you receive source code or can get it
26	+	if you want it, that you can change the software or use pieces of it
27	+	in new free programs; and that you know you can do these things.
28	+
29	+	To protect your rights, we need to make restrictions that forbid
30	+	anyone to deny you these rights or to ask you to surrender the rights.
31	+	These restrictions translate to certain responsibilities for you if you
32	+	distribute copies of the software, or if you modify it.
33	+
34	+	For example, if you distribute copies of such a program, whether
35	+	gratis or for a fee, you must give the recipients all the rights that
36	+	you have. You must make sure that they, too, receive or can get the
37	+	source code. And you must show them these terms so they know their
38	+	rights.
39	+
40	+	We protect your rights with two steps: (1) copyright the software, and
41	+	(2) offer you this license which gives you legal permission to copy,
42	+	distribute and/or modify the software.
43	+
44	+	Also, for each author's protection and ours, we want to make certain
45	+	that everyone understands that there is no warranty for this free
46	+	software. If the software is modified by someone else and passed on, we
47	+	want its recipients to know that what they have is not the original, so
48	+	that any problems introduced by others will not reflect on the original
49	+	authors' reputations.
50	+
51	+	Finally, any free program is threatened constantly by software
52	+	patents. We wish to avoid the danger that redistributors of a free
53	+	program will individually obtain patent licenses, in effect making the
54	+	program proprietary. To prevent this, we have made it clear that any
55	+	patent must be licensed for everyone's free use or not licensed at all.
56	+
57	+	The precise terms and conditions for copying, distribution and
58	+	modification follow.
59	+
60	+	GNU GENERAL PUBLIC LICENSE
61	+	TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
62	+
63	+	0. This License applies to any program or other work which contains
64	+	a notice placed by the copyright holder saying it may be distributed
65	+	under the terms of this General Public License. The "Program", below,
66	+	refers to any such program or work, and a "work based on the Program"
67	+	means either the Program or any derivative work under copyright law:
68	+	that is to say, a work containing the Program or a portion of it,
69	+	either verbatim or with modifications and/or translated into another
70	+	language. (Hereinafter, translation is included without limitation in
71	+	the term "modification".) Each licensee is addressed as "you".
72	+
73	+	Activities other than copying, distribution and modification are not
74	+	covered by this License; they are outside its scope. The act of
75	+	running the Program is not restricted, and the output from the Program
76	+	is covered only if its contents constitute a work based on the
77	+	Program (independent of having been made by running the Program).
78	+	Whether that is true depends on what the Program does.
79	+
80	+	1. You may copy and distribute verbatim copies of the Program's
81	+	source code as you receive it, in any medium, provided that you
82	+	conspicuously and appropriately publish on each copy an appropriate
83	+	copyright notice and disclaimer of warranty; keep intact all the
84	+	notices that refer to this License and to the absence of any warranty;
85	+	and give any other recipients of the Program a copy of this License
86	+	along with the Program.
87	+
88	+	You may charge a fee for the physical act of transferring a copy, and
89	+	you may at your option offer warranty protection in exchange for a fee.
90	+
91	+	2. You may modify your copy or copies of the Program or any portion
92	+	of it, thus forming a work based on the Program, and copy and
93	+	distribute such modifications or work under the terms of Section 1
94	+	above, provided that you also meet all of these conditions:
95	+
96	+	a) You must cause the modified files to carry prominent notices
97	+	stating that you changed the files and the date of any change.
98	+
99	+	b) You must cause any work that you distribute or publish, that in
100	+	whole or in part contains or is derived from the Program or any
101	+	part thereof, to be licensed as a whole at no charge to all third
102	+	parties under the terms of this License.
103	+
104	+	c) If the modified program normally reads commands interactively
105	+	when run, you must cause it, when started running for such
106	+	interactive use in the most ordinary way, to print or display an
107	+	announcement including an appropriate copyright notice and a
108	+	notice that there is no warranty (or else, saying that you provide
109	+	a warranty) and that users may redistribute the program under
110	+	these conditions, and telling the user how to view a copy of this
111	+	License. (Exception: if the Program itself is interactive but
112	+	does not normally print such an announcement, your work based on
113	+	the Program is not required to print an announcement.)
114	+
115	+	These requirements apply to the modified work as a whole. If
116	+	identifiable sections of that work are not derived from the Program,
117	+	and can be reasonably considered independent and separate works in
118	+	themselves, then this License, and its terms, do not apply to those
119	+	sections when you distribute them as separate works. But when you
120	+	distribute the same sections as part of a whole which is a work based
121	+	on the Program, the distribution of the whole must be on the terms of
122	+	this License, whose permissions for other licensees extend to the
123	+	entire whole, and thus to each and every part regardless of who wrote it.
124	+
125	+	Thus, it is not the intent of this section to claim rights or contest
126	+	your rights to work written entirely by you; rather, the intent is to
127	+	exercise the right to control the distribution of derivative or
128	+	collective works based on the Program.
129	+
130	+	In addition, mere aggregation of another work not based on the Program
131	+	with the Program (or with a work based on the Program) on a volume of
132	+	a storage or distribution medium does not bring the other work under
133	+	the scope of this License.
134	+
135	+	3. You may copy and distribute the Program (or a work based on it,
136	+	under Section 2) in object code or executable form under the terms of
137	+	Sections 1 and 2 above provided that you also do one of the following:
138	+
139	+	a) Accompany it with the complete corresponding machine-readable
140	+	source code, which must be distributed under the terms of Sections
141	+	1 and 2 above on a medium customarily used for software interchange; or,
142	+
143	+	b) Accompany it with a written offer, valid for at least three
144	+	years, to give any third party, for a charge no more than your
145	+	cost of physically performing source distribution, a complete
146	+	machine-readable copy of the corresponding source code, to be
147	+	distributed under the terms of Sections 1 and 2 above on a medium
148	+	customarily used for software interchange; or,
149	+
150	+	c) Accompany it with the information you received as to the offer
151	+	to distribute corresponding source code. (This alternative is
152	+	allowed only for noncommercial distribution and only if you
153	+	received the program in object code or executable form with such
154	+	an offer, in accord with Subsection b above.)
155	+
156	+	The source code for a work means the preferred form of the work for
157	+	making modifications to it. For an executable work, complete source
158	+	code means all the source code for all modules it contains, plus any
159	+	associated interface definition files, plus the scripts used to
160	+	control compilation and installation of the executable. However, as a
161	+	special exception, the source code distributed need not include
162	+	anything that is normally distributed (in either source or binary
163	+	form) with the major components (compiler, kernel, and so on) of the
164	+	operating system on which the executable runs, unless that component
165	+	itself accompanies the executable.
166	+
167	+	If distribution of executable or object code is made by offering
168	+	access to copy from a designated place, then offering equivalent
169	+	access to copy the source code from the same place counts as
170	+	distribution of the source code, even though third parties are not
171	+	compelled to copy the source along with the object code.
172	+
173	+	4. You may not copy, modify, sublicense, or distribute the Program
174	+	except as expressly provided under this License. Any attempt
175	+	otherwise to copy, modify, sublicense or distribute the Program is
176	+	void, and will automatically terminate your rights under this License.
177	+	However, parties who have received copies, or rights, from you under
178	+	this License will not have their licenses terminated so long as such
179	+	parties remain in full compliance.
180	+
181	+	5. You are not required to accept this License, since you have not
182	+	signed it. However, nothing else grants you permission to modify or
183	+	distribute the Program or its derivative works. These actions are
184	+	prohibited by law if you do not accept this License. Therefore, by
185	+	modifying or distributing the Program (or any work based on the
186	+	Program), you indicate your acceptance of this License to do so, and
187	+	all its terms and conditions for copying, distributing or modifying
188	+	the Program or works based on it.
189	+
190	+	6. Each time you redistribute the Program (or any work based on the
191	+	Program), the recipient automatically receives a license from the
192	+	original licensor to copy, distribute or modify the Program subject to
193	+	these terms and conditions. You may not impose any further
194	+	restrictions on the recipients' exercise of the rights granted herein.
195	+	You are not responsible for enforcing compliance by third parties to
196	+	this License.
197	+
198	+	7. If, as a consequence of a court judgment or allegation of patent
199	+	infringement or for any other reason (not limited to patent issues),
200	+	conditions are imposed on you (whether by court order, agreement or
201	+	otherwise) that contradict the conditions of this License, they do not
202	+	excuse you from the conditions of this License. If you cannot
203	+	distribute so as to satisfy simultaneously your obligations under this
204	+	License and any other pertinent obligations, then as a consequence you
205	+	may not distribute the Program at all. For example, if a patent
206	+	license would not permit royalty-free redistribution of the Program by
207	+	all those who receive copies directly or indirectly through you, then
208	+	the only way you could satisfy both it and this License would be to
209	+	refrain entirely from distribution of the Program.
210	+
211	+	If any portion of this section is held invalid or unenforceable under
212	+	any particular circumstance, the balance of the section is intended to
213	+	apply and the section as a whole is intended to apply in other
214	+	circumstances.
215	+
216	+	It is not the purpose of this section to induce you to infringe any
217	+	patents or other property right claims or to contest validity of any
218	+	such claims; this section has the sole purpose of protecting the
219	+	integrity of the free software distribution system, which is
220	+	implemented by public license practices. Many people have made
221	+	generous contributions to the wide range of software distributed
222	+	through that system in reliance on consistent application of that
223	+	system; it is up to the author/donor to decide if he or she is willing
224	+	to distribute software through any other system and a licensee cannot
225	+	impose that choice.
226	+
227	+	This section is intended to make thoroughly clear what is believed to
228	+	be a consequence of the rest of this License.
229	+
230	+	8. If the distribution and/or use of the Program is restricted in
231	+	certain countries either by patents or by copyrighted interfaces, the
232	+	original copyright holder who places the Program under this License
233	+	may add an explicit geographical distribution limitation excluding
234	+	those countries, so that distribution is permitted only in or among
235	+	countries not thus excluded. In such case, this License incorporates
236	+	the limitation as if written in the body of this License.
237	+
238	+	9. The Free Software Foundation may publish revised and/or new versions
239	+	of the General Public License from time to time. Such new versions will
240	+	be similar in spirit to the present version, but may differ in detail to
241	+	address new problems or concerns.
242	+
243	+	Each version is given a distinguishing version number. If the Program
244	+	specifies a version number of this License which applies to it and "any
245	+	later version", you have the option of following the terms and conditions
246	+	either of that version or of any later version published by the Free
247	+	Software Foundation. If the Program does not specify a version number of
248	+	this License, you may choose any version ever published by the Free Software
249	+	Foundation.
250	+
251	+	10. If you wish to incorporate parts of the Program into other free
252	+	programs whose distribution conditions are different, write to the author
253	+	to ask for permission. For software which is copyrighted by the Free
254	+	Software Foundation, write to the Free Software Foundation; we sometimes
255	+	make exceptions for this. Our decision will be guided by the two goals
256	+	of preserving the free status of all derivatives of our free software and
257	+	of promoting the sharing and reuse of software generally.
258	+
259	+	NO WARRANTY
260	+
261	+	11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
262	+	FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
263	+	OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
264	+	PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
265	+	OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
266	+	MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
267	+	TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
268	+	PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
269	+	REPAIR OR CORRECTION.
270	+
271	+	12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
272	+	WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
273	+	REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
274	+	INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
275	+	OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
276	+	TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
277	+	YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
278	+	PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
279	+	POSSIBILITY OF SUCH DAMAGES.
280	+
281	+	END OF TERMS AND CONDITIONS
282	+
283	+	How to Apply These Terms to Your New Programs
284	+
285	+	If you develop a new program, and you want it to be of the greatest
286	+	possible use to the public, the best way to achieve this is to make it
287	+	free software which everyone can redistribute and change under these terms.
288	+
289	+	To do so, attach the following notices to the program. It is safest
290	+	to attach them to the start of each source file to most effectively
291	+	convey the exclusion of warranty; and each file should have at least
292	+	the "copyright" line and a pointer to where the full notice is found.
293	+
294	+	<one line to give the program's name and a brief idea of what it does.>
295	+	Copyright (C) <year> <name of author>
296	+
297	+	This program is free software; you can redistribute it and/or modify
298	+	it under the terms of the GNU General Public License as published by
299	+	the Free Software Foundation; either version 2 of the License, or
300	+	(at your option) any later version.
301	+
302	+	This program is distributed in the hope that it will be useful,
303	+	but WITHOUT ANY WARRANTY; without even the implied warranty of
304	+	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
305	+	GNU General Public License for more details.
306	+
307	+	You should have received a copy of the GNU General Public License
308	+	along with this program; if not, write to the Free Software
309	+	Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
310	+
311	+
312	+	Also add information on how to contact you by electronic and paper mail.
313	+
314	+	If the program is interactive, make it output a short notice like this
315	+	when it starts in an interactive mode:
316	+
317	+	Gnomovision version 69, Copyright (C) year name of author
318	+	Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
319	+	This is free software, and you are welcome to redistribute it
320	+	under certain conditions; type `show c' for details.
321	+
322	+	The hypothetical commands `show w' and `show c' should show the appropriate
323	+	parts of the General Public License. Of course, the commands you use may
324	+	be called something other than `show w' and `show c'; they could even be
325	+	mouse-clicks or menu items--whatever suits your program.
326	+
327	+	You should also get your employer (if you work as a programmer) or your
328	+	school, if any, to sign a "copyright disclaimer" for the program, if
329	+	necessary. Here is a sample; alter the names:
330	+
331	+	Yoyodyne, Inc., hereby disclaims all copyright interest in the program
332	+	`Gnomovision' (which makes passes at compilers) written by James Hacker.
333	+
334	+	<signature of Ty Coon>, 1 April 1989
335	+	Ty Coon, President of Vice
336	+
337	+	This General Public License does not permit incorporating your program into
338	+	proprietary programs. If your program is a subroutine library, you may
339	+	consider it more useful to permit linking proprietary applications with the
340	+	library. If this is what you want to do, use the GNU Library General
341	+	Public License instead of this License.
342	+

Add docs and README