search

yedino / galaxy42

Other
11 stars 25 forks source link

readme

Build Status Coverage Status Pre-alpha IRC #antinet icann.irc.meshnet.pl

This program is not yet ready nor secure, do not use it in this version. It is Copyrighted, see LICENCE.txt

该程序还没有准备好，也不安全，在这个版本中不使用它. 它是有版权的，读文件 LICENCE.txt

This program creates an secure connection between computers (like VPN).

Works on: Debian 9 (Stretch) on amd64 is recommended, also other Linuxes, Windows 7, 8, 10, Mac OS X

To run from sources, just use menu ./menu and select install, then build, then run - for supported systems, or keep reading.

To use this program from Command Line (as regular user, or as root) simply:

That is all! Now your computers are connected together, try ping6 VIRTUALIP1 from 2nd computer, all connections (browser, ftp, ssh etc) should work too.

To build this program from source we recommend:

Backup: your private keys that give ownership of your virtual IP address by default are in ~/.config/antinet/ (or just the galaxy42/wallet there).

This program will allow to do much more in future (full public mesh, scoring, donations/payments) but this are plans for advanced testers (see below).

For more details, including correct naming and glossary, and advanced technical topics for developers and "hackers", see also: doc/hacking.md.

Release notes

Version v0.3.3a (pre-alpha)

Older release notes are in Changelog.md.

Using pre-built binary

You can download the binary releases from: https://github.com/yedino/galaxy42-release/ https://github.com/yedino/galaxy42-release/tree/master/tests-insecure search there for the version that you want to use.

Security: write down a checksum of the downloaded file if you care about security for verification in future, also check if other people confirm same checksum of binary files, and you can also confirm yourself that it matches given source code (see below - "Security of binary install").

Security:

Planned:

The source code is NOT yet reviewed, expect it to have bugs and exploits. For now we recommend to use it only in isolated VM or better yet on a separated test computer.

When you build program from source, check the file [SECURITY.txt] for list of dependencies that you MUST monitor for security updates!

Security of binary download/install:

We offer binary builds on web page:

https://github.com/yedino/galaxy42-release/ in future address will be also: https://download.yedino.com/

The files there will be GPG signed, see below "Root of trust".

Write down a checksum of the downloaded file if you care about security for verification in future: you can check if the files are GPG-signed by us (they always should be), and look around if other trusted people repeated our Gitian builds and can testify they have same resulting checksum.

In addition you can "trust no one" and repeat the Gitian build now or in future and you will get identical checksum of resulting binary files.

If you repeat the Gitian build in far future (when there were updates to relevant parts of the OS that we use inside Gitian), then you must somehow provide identical version of the packages, otherwise it could change the checksum.

Security of binary auto-updates:

Not implemented yet.

Security and verificatin of source code:

You can confirm that source code is indeed created by the developers - git tags are signed, and after them (e.g. on some work in progress branch) all following git commits (including git merges) are also signed.

Or else, for not-tagged versions:

Script that can help speed up this process is being written, e.g. one good version of it is: sha512 3ed9cf88d3d78ced3a7326a05bc954695cb36b5802abca309745196bfe498e679a2f91c1df3e4ffcef852e3a203406959d565f5e78a8364d0438e99a6e9a7ad0 of file antinet/tools/git_pretty_signature.py in project Antinet. (New versions will be better, though review the code before runnig it anyway).

Tasks

Running benchmarks: Use ./menu See [[src-tools/netutils/README-bench.txt]] for details.

Organizations and projects

Advanced use

Sudo/Cap on Linux

Program can be given higher privileges on start in various ways, on Linux.

Method name You are user... ... and run command: If binary is setcap If binary is SUID Then config directory will be used Then tuntap works? Good idea?
user+setcap alice ./tunserver.elf if yes if no /home/alice/.config/ tuntap OK Yes, recommended
user+setcap alice HOME="$HOME/profile1/" ./tunserver.elf if yes if no /home/alice/.config/ tuntap OK Yes, recommended
user+sudo alice ./tunserver.elf if NO if no /home/alice/.config/ tuntap OK Yes, if you can't use file setcap
user+sudo alice sudo HOME="$HOME/profile1/" ./tunserver.elf --home-env if NO if no /home/alice/profile1/.config/ tuntap OK Yes, if you can't use file setcap
root+etc root ./tunserver.elf --root-mode (any) if no /etc/ tuntap OK Yes, daemons starting from root. Will read files from /etc/ and then drop to given user. TODO NOT YET IMPLEMENTED
(NO!) root ./tunserver.elf (any) if no /etc/ tuntap OK No! program will abort; or try to drop out to user who gained this root (e.g. from sudo su)
(NO!) alice sudo HOME="$HOME" ./tunserver.elf if yes if no /home/alice/.config/ tuntap OK Allowed; but sudo not needed
(NO!) root ./tunserver.elf (any) if no /root/.config/ tuntap OK No! NOT SECURE
(NO!) alice sudo ./tunserver.elf (any) if no /root/.config/ tuntap OK No! no access to root files

Other combinations (of this conditions, exporting env HOME, etc) are not supported currently.

Config file actually used can be this path plus "/antinet/", e.g. "/home/alice/.config/antinet/".



* * *
* * *
* * *

Advanced topics - for developers and for future.

---> Users, developers, read also the HOWTO section it contains friendly FAQ how to use/develop/hack this :) <---

Galaxy42 - Small experimental network in category of Meshnet, VPN, IP-hash.

Title: Galaxy42
Status: Experimental, pre-alpha, NOT reviewed, NOT secure.

Do not use this network for any purpose at all (yet!) it contains
bugs, probably including vulns. Could be ok to try it in a VM.
Intended ONLY for developers (for now).

Finall version will be aimed to all users on Windows, Linux, Mac and
other systems.

NETWORK TYPE:

* Meshnet - it will be possible to set up the net with minimal config
(and later zeroconf), no nodes are centralized.

* VPN - it will provide end-to-end encryption and authentication,
and IP access even to places with no own traditional Internet-accessible IP.

* IP-Hash - the IP address is hash (e.g. of public key) and therefore
it can be assigned in some decentralized way (e.g. created and owned by user,
as hash of his own public-key to which only he has private-key).

This network is similar in principle to Cjdns network.

GOALS:

We aim with it to test possible solutions to some challenges discovered in Cjdns:

1) Not optimal speed in even 1-to-1 connection over Gigabit link (e.g. on Linux).
2) Not close to optimal global speed, probably because of routing creating not so good routes.
3) Not stable connections.

Optionally, for the main Antinet project we plan to test:

4) Possible integrated micro "payments" between nodes, especially "paying" just with
own resources (I route for you - if you route for me) to allow node owner to demand
cooperation from other participants of the network if they want to get his help.

### HOWTO

Q: How to use Galaxy42?
A: [use] See top of this README for instructions - or just run the program and follow instructions on screen.

Q: How to commit my work using Git?
A: {git.model} First see {devel}.
Create a branch, work there using `git commit -s` to sign each commit. Make a pull request.
Project technical maintainer will the git merge -s your code.
Do NOT rebase our code on top of work - or if you do so then you need to:
sign again all commit using e.g. `git reset --hard` and `git cherry-pick` and `git commit --ammend -s`.
See if all commits are signed using e.g. `git log --show-signature`.
We will merge your commit using e.g. `git merge -S --verify-signatures`.
As result, each and every commit (and merge commits) will be GPG signed.
In addition, tags (that we created with `git tag -s`) will be signed too, by proper developer.

Q: How to develop Galaxy42?
A: [devel] Read most of questions here first, including [devel.demo], [devel.contact].

Q: What is the licence?
A: See the LICENCE-by-Antinet.txt file and other such files.

Q: How to develop Galaxy42?
A: [devel] See LICENCE information first. Read most of questions here first, including [devel.demo], [devel.contact].

Q: How to contact developers?
A: [devel.contact] (Disclaimer: this is NOT a contact for legal matters - all such messages will be ignored; Wait for reply at least 12 hours;
On IRC user names are not protected, and do not trust no one. We will never ask you to give us any passwords or run some untrusted not signed code!)
Contact us on IRC server icann.irc.meshnet.pl on channel #meshnet or #antinet (that for now is also about Galaxy42).

Q: How to see a demo how program works?
A: [devel.demo] First build the program, and then choose one of methods:

1. Run program as ./tunserver.elf --devel --demo foo to run test foo. Existing tests include test "foo",
test "bar", and other real tests.
[TODO] You can see list of the possible tests by running it with "help" demo,
so as:
./tunserver.elf --devel --demo help

2. In directory ./config crete a file config/demo.conf. In this file write a single line like `demo=bar`;
Then run the program with `make run` or with `./tunserver.elf --devel`
It should run a demo "bar" and write bar on screen (read the debug messages).
If you change that text in file to `demo=foo` then it runs test Foo.
If something does not work then see debug to figure it out.
You can now write other demo name in the config file and run tests again.
Set demo to "list" or "help" to see list of possible demo options [TODO].

3. If you just run program with `--devel` it will run the hardcoded demo,
as set in code in variable `g_demoname_default`.
If you start working on a new branch you could set it there to other value
to run your test - see [devel.newthing]

Q: How to develop something new?
A: [devel.newthing] (First read [devel]) and then create git branch named like "wip_galaxy_SOMENAME"
where SOMENAME is a nice name summarizing on what you do work.
Then create also a demo for it (see how other demos are done, see function run_mode_developer,
see demo `developer_tests::wip_galaxy_route_doublestar` that can be used in simulation of few nodes etc)

Q: How to debug a crash, memory leak, etc, how to run in valgrind/gdb
A: [debug.nocap] You can use gdb and valgrind, but if you have a problem there that the CAP privilages level
block your debug tool from working (as is the case with some hardened platforms) then if you can run
a test, or a demo [devel.demo] that does not require net CAP privilages etc,
then use the binary file that is not trying to get CAP rights,
the file `nocap-*` binary, e.g.: `nocap-tunserver.elf`
e.g.: `valgrind  ./nocap-tunserver.elf --devel`
e.g.: `valgrind  ./nocap-tunserver.elf --devel  --demo foo`

### FAQ

This FAQ contains some common problems and their solutions.
Problems that are solved will be moved to

Q: Build failed with: error like `cpp_int.hpp` or `right operand of shift expression` or `limb_type`
e.g.:
`
In file included from /usr/include/boost/config.hpp:61:0,
from /usr/include/boost/cstdint.hpp:36,
from /usr/include/boost/multiprecision/cpp_int.hpp:11,
from gcc6.cpp:1:
/usr/include/boost/multiprecision/cpp_int.hpp:193:4: error: right operand of shift expression ‘(1u << 63u)’ is >= than the precision of the left operand [-fpermissive]
BOOST_STATIC_CONSTANT(limb_type, sign_bit_mask = 1u << (limb_bits - 1));
`
A: Your system seems to include a broken version of lib boost (see bug https://svn.boost.org/trac/boost/ticket/12181),
if system update doesn't fix it then you can for now work around by
building with option: `USE_BOOST_MULTIPRECISION_DEFAULT=0 ./do`
(or set it in ccmake . and then build).

Q: Using gitian has error regarding Xenial `/usr/share/debootstrap/scripts/xenial`, e.g.:
`
E: No such script: /usr/share/debootstrap/scripts/xenial
Error occured, will exit (to create Xenial image (do you have the Xenial template?))
`
A: Older systems (e.g. Debian Jessie) do not include the template script file of Xenial.
Now our Gitian script should automatically work around this problem.
Some other solutions (if needed) would be to:
sudo cp -i galaxy42/contrib/gitian-debootstrap/scripts/xenial   /usr/share/debootstrap/scripts/
or install other version of system's debootstrap (e.g. backports).

Q: Errors like `profiling:invalid arc tag` or `profiling:invalid number of counters`
A: Do an `make clean` and try again. They can show up when you run more then once a build with coveralls/coverage active.
That option is intended for use by automated tools only, and they start in clearn environment.
You can also try: `find . -name "*.gcda" -print0 | xargs -0 rm`.
See: http://stackoverflow.com/questions/22519530/dozens-of-profilinginvalid-arc-tag-when-running-code-coverage-in-xcode-5