diff --git a/BUILD.md b/BUILD.md new file mode 100644 index 00000000..b3729607 --- /dev/null +++ b/BUILD.md @@ -0,0 +1,61 @@ +Build instructions +================== + +Third-party libraries +--------------------- + +FreeLAN depends on the following libraries: + +- libcurl4 +- boost +- OpenSSL +- iconv (Windows) + +Generally Linux users can just use the binaries provided by their package manager, but other platforms such as Mac OSX or Windows may need to build these libraries explicitely. + +To build the third-party libraries, you can use [teapot](https://github.com/freelan-developers/teapot). Check its [documentation](http://teapot-builder.readthedocs.org/en/latest/) for details, or just type the following command at the root of FreeLAN's repository: + +> teapot build + +This will build everything inside `third-party`. Once that is done, you can proceed with the next steps. + +### Debian Linux + +To install the required dependencies on Debian Linux (Or Ubuntu), type the following command: + +> sudo apt-get install scons python libssl-dev libcurl4-openssl-dev libboost-system-dev libboost-thread-dev libboost-program-options-dev libboost-filesystem-dev libboost-iostreams-dev + +Building FreeLAN +---------------- + +FreeLAN is written in C++11. Make sure your C++ compiler is recent enough and supports this standard. On Linux for instance, you need at least `gcc 4.9.2` for things to go fine. + +FreeLAN uses [scons](http://www.scons.org/) as its build system on POSIX-like systems (basically everything except Windows). + +To build the main binary, just type: + +> scons + +To build everything in the directory (including samples), type instead: + +> scons samples + +To build then install everything into a specific directory, type instead: + +> scons install --prefix=/usr/local/ + +### Debugging + +If the debug-level logging exposed with the `-d` parameter to freelan does not expose enough information to assist development or bug-finding, it is possible to enable additional debug information at build time with: + +> scons all --mode=debug + +Be aware that this will produce a significant amount of logging information and is not intended for production use. + +### Windows + +You will need Microsoft Visual Studio 2013 to compile freelan. All projects come with a `.vcxproj` file for all the targets (debug/release and x86/x64). + +The root directory also contains a solution file (`.sln`) that references all the sub-projects. + +The resulting binaries will be located in the [install](install) directory. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..4ff6fdf8 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,13 @@ +Contributing +============ + +Contributions to FreeLAN are greatly appreciated. + +To improve the chances of your pull-requests to be accepted, make sure that: + +- Your code compiles, on all platforms. +- Your changes don't introduce a security weakness or encourage a bad usage. +- Your changes are of public utility. +- There aren't (too many) spelling or grammar mistakes. + +Feel free to suggest improvements, ideas or to add new features. Do not hesitate to ask for help on the [mailing-list](http://freelan.org/development.html) if you need some ! diff --git a/README.linux b/README.linux deleted file mode 100644 index 9c3a43fa..00000000 --- a/README.linux +++ /dev/null @@ -1,35 +0,0 @@ -Building on a Linux host -======================== - -build-time requirements ------------------------ - -Make sure you have the necessary build-time requirements installed - -- scons -- python-argparse or python >= 2.7 -- libssl-dev -- libcurl4-openssl-dev -- libboost-system-dev -- libboost-thread-dev, -- libboost-program-options-dev -- libboost-filesystem-dev, -- libboost-iostreams-dev - -building from source --------------------- - -check out the git master branch of freelan-all and issue the "scons all" command - -building for Debian, Ubuntu and derivates ------------------------------------------ - -There is work going on to have proper Debian packaging available. Please check back soon. - -Install "debhelper libssl-dev libcurl4-openssl-dev libboost-system-dev libboost-thread-dev libboost-program-options-dev libboost-filesystem-dev libboost-iostreams-dev scons python-argparse" packages as root to satisfy compile-time dependencies. - - -building for other distros --------------------------- - -Packaging patches and instructions will be gladly accepted diff --git a/README.md b/README.md index c939d008..b1eab456 100644 --- a/README.md +++ b/README.md @@ -1,93 +1,49 @@ -[![Stories in Ready](https://badge.waffle.io/freelan-developers/freelan-all.png?label=ready&title=Ready)](https://waffle.io/freelan-developers/freelan-all) -freelan-all -=========== +FreeLAN +======= -A super-project that includes all FreeLAN related projects and provides scripts to generate installers. +A peer-to-peer, secure, easy-to-setup, multi-platform, open-source, highly-configurable VPN software. -For help regarding the configuration, take a look at the [wiki](https://github.com/freelan-developers/freelan-all/wiki). +Installation +------------ -Binaries --------- +FreeLAN is available on Windows, Mac OSX and Linux (Debian-based distributions). Check the [official website](http://www.freelan.org) for installers. -It contains the following binaries: +If your platform is not officially supported, dot not despair and try to build-it yourself ! Check the [build instructions](BUILD.md) for details on how to do that. -- freelan - The FreeLAN binary (acts as a service on Windows and as a daemon on Linux/Mac OSX) +Quick-start +----------- -Libraries ---------- - -It contains the following projects: - - - cryptoplus - A C++ wrapper around the OpenSSL cryptographic library. - - iconvplus - A C++ wrapper around the iconv library. - - fscp - The FreeLAN Secure Channel protocol and its C++ implementation. - - asiotap - A C++ library to control virtual network interfaces also known as "TAP adapters". - - freelan - The FreeLAN C++ library. - - kfather - A C++ JSON parser/producer with a terrible name. - -Building --------- - -See the README file specific to your host environment for general setup instructions. - -### Third-party - -The build relies on several third-parties. Generally Linux users won't need these, but other platforms such as MacOS or Windows may need these. - -To build those, install the Python command `teapot` using the following command: - -> pip install teapot - -Once you have `teapot` in your `PATH` (should be the case automatically), just type: - -> teapot build +FreeLAN can be configured to support any network topology, be it a traditional client-server structure or a full-mesh one. The emulated network can operate at the Ethernet or at the IPv4/IPv6 levels. Security can be achieved through the use of certificates or via a simple shared passphrase. -To build everything inside `third-party`. Once that is done, you can proceed with the next steps. +For instance, creating a simple VPN node can be done with: -### Common code +> freelan --security.passphrase "my secret" -This directory contains a `SConstruct` file to build the contained projects. +This will start a VPN node, listening for connections on all interfaces on the port UDP:12000. The node will pick the default 9.0.0.1 IPv4 address inside the emulated network. -The default target (`install`) builds and installs all the main FreeLAN binary. +To specify the IPv4 address inside the emulated network, you can specify the `tap_adapter.ipv4_address_prefix_length` option, like so: -To do that, just type: +> freelan --security.passphrase "my secret" --tap_adapter.ipv4_address_prefix_length=9.0.0.2/24 -> scons +It is important that all nodes have different virtual IP addresses. -To build everything in the directory (all samples), type instead: +Frequently Asked Questions +-------------------------- -> scons samples +## Is there a graphical interface ? -To build then install everything into a specific directory, type instead: - -> scons install --prefix=/usr/local/ - -### Windows - -You will need Microsoft Visual Studio 2013 to compile freelan. All projects come with a `.vcxproj` file for all the targets (debug/release and x86/x64). - -The root directory also contains a solution file (`.sln`) that references all the sub-projects. - -### Debugging - -If the debug-level logging exposed with the `-d` parameter to freelan does not expose enough information to assist development or bug finding, it is possible to enable additional debug information at build time with: - -> scons all --mode=debug +A graphical user interface is planned but nothing is made public yet. You will just have to be patient :) -Be aware that this will produce a significant amount of logging information and is not intended for general use. +## Can I use FreeLAN to access forbidden websites/websites in other countries with restrictions ? +FreeLAN is not a service, it's a software. You can configure it to reach that goal easily, but you'll need an exit-point (a server, a friendly-computer at the right location) on which you can run FreeLAN too. **It will always take a minimum of 2 nodes to create a VPN network**. -Graphical User Interface ------------------------- +Contributions +------------- -A graphical user interface is planned but nothing is made public yet. You will just have to be patient :) +Check the [contributions guidelines](CONTRIBUTING.md). Packaging --------- -See the `README.md` file into the `packaging` directory. - -Does the project have a website ? ---------------------------------- - -You may find the [git repository](https://github.com/freelan-developers/freelan-all) on github. +Check the [packaging instructions](packaging/README.md).