Package: asylum
Asylum=======Intro------A lib to use the unshare/clone syscalls from linux directly. alsoprovides support for seccomp for applications that have beenspecifically written to use itQuick start Guide------------------# Clone the repository$ hg clone http://code.pocketnix.org/asylum$ cd asylum# Built a temporary/Zero install enviroment$ virtualenv env$ . env/bin/activate$ python ./setup.py install# Launch the program$ sudo asylum start -HPMIN --hostname example.com #NOTE: needs root priviliges to run$ hostnamehostname should now spit out 'example.org' in the asylum jail and remainunchanged in another terminal. to confirm that asylum has fully isolatedthe enviroment, try setting the hostname in the asylum jail and confirmthat the hostname for your system has not changedUses-----* Executing unsafe code* More advanced chrooting* OS virtualisation/bootstrapping* Network Simulation* Experimenting with different setups* Preinstallation steps for new machines* Vhosting* Performing MITM on locally running applicationsGoals------To provide several security and virtualisation primitives that caneasily be integrated into python programs.#. Provide Strong simple primitives to existing python programsWhere possible make these drop in replacements (eg PEP-3143)#. Provide a virtualenv like tool for creating and running virtualenvironments#. Provide wrappers for low level syscallsFeatures---------* Direct setting of hostname* Direct mounting of filesystems without calling /sbin/mount* Setting and dropping of capabilities* Syscall wrapper generation for the brave* pivot_root support for full isolation* prctl syscall* clone/unshare syscall supportComing Soon------------Features that are planned but have not yet come to fruition* PEP-3143 daemon process support (http://www.python.org/dev/peps/pep-3143/)increases the security of the chroot option* Recording of namespace state/status for querying (start/stop)* Optional management daemon* Optional web interface for management daemon* Basic image setup hooks* Command orientated cmdline args (similar to virtualenv)* Plugin support* Config file support* Reconnect to running namespace (setns)Requirements-------------* A recent linux kernel with cgroups and namespace support(Tested on a 2.6.37 hand compiled kernel)* an x86 processor (32bit or 64bit), support for other archs isavailable on request. this syscall constants just need to beupdated* python >= 3.0* argparse moduleOR* python >= 3.2OR* python >= 2.7OR* pypy >= 1.5Compiling a namespace capable Kernel-------------------------------------If your linux kernel does not have the required features then you maybe able to compile your own kernel by downloading the source packagesfor your distribution and compiling a kernel yourself.if you are using a graphical tool (eg as launched by typing "make nconfig")then you will need to ensure the following options are enabledNamespaces+++++++++++General Setup--> Namespaces Support--> UTS Namespace--> IPC Namespace--> User Namespace--> PID Namespace--> Network NamespaceCgroups++++++++General Setup--> Control Group Support--> Enable options as requiredif invoking "make config" to set the required options or editing an existingkernel config (eg one taken from /proc/config or /proc/config.gz) then theconfig options you need to change can be obtained by running "asylum -d" toperform auto detection of the settings and listing their name and currentstateyou may wish to enable basic routing support (normmaly enabled by default)as well as etun and macvlan support. seccomp supportNetworking+++++++++++Device Drivers--> Network device support--> MAC-VLAN support-->Virtual ethernet pair deviceSeccomp++++++++Processor type and features--> Enable seccomp to safely compute untrusted bytecodeNotes------The kernel documentation/manpages do not always line up with exactly what linuxdoes, some syscalls raise EPERM incorectly (eg pivot_root and EBUSY), whereposible i have tried to put all edge cases in the exception message or asnotes in the src however if you find new ones let me know asap atcode@pocketnix.orgExamples---------The following example shows how to create a namespace with its ownseparate network and idea of the machines hostname and domain, youcan make changes to the hostname and interfaces without affectingyour main workspace. as these are lightweight you can easily create100's of namespaces to perform things like creating virtual networks.for creating network 'pipes' between namespaces take a look at vtunor refer to the documents on http://www.pocketnix.org (coming soon).to share the main Ethernet interface between multiple namespaces itis recommended to use macvlan if you wish to use features such astcpdump or dhcp in the guest namespace, otherwise routing may suffice$ sudo ipython>>> import asylum# Here we enable IPC, UTS (kernel domain name) and NET namespaces>>> asylum.isolate(None, False, False, True, False, True, True)>>> !ip ad sh13: lo: <LOOPBACK> mtu 16436 qdisc noop state DOWNlink/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:0014: sit0: <NOARP> mtu 1480 qdisc noop state DOWNlink/sit 0.0.0.0 brd 0.0.0.0>>> !hostname thisisatest>>> !domainname example.com# now go to a seperate terminal and enter the following$ hostname; domainname# Now go back to ipython and enter the following>>> import socket>>> socket.gethostname()'thisisatest'Getting Support----------------I am more than willing to help people get the code up and running or getup to speed on developing with the code, drop me a line #insane-asylum onirc.freenode.net, xmpp://code@conference.pockentix.org or emailcode@pocketnix.orgif you have bug reports send them in, i am happy to fix them. same goesfor feature requests and comments on my code quality.if you are using this in production let me know :DLinks------* Documents on LXC and networking with unshare: http://www.pocketnix.org