forked from libremesh/libremesh.github.io
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdevelopment.txt
205 lines (141 loc) · 11 KB
/
development.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
---
title: Development
ref: development
lang: en
---
Development
===========
== The Source Code
The code is stored inside a git tree which contains all branches and releases.
All repositories can be browsed online through
https://github.com/libremesh/[GitHub].
Most of the development happens in the _lime-packages_ git repository which can be browsed on https://github.com/libremesh/lime-packages[GitHub] or downloaded using git:
----
git clone https://github.com/libremesh/lime-packages.git
cd lime-packages
----
== Compiling LibreMesh from source code
This procedure has been tested on GNU/Linux, on other systems it could require some modifications or it can be run in a Linux virtual machine. Generally, the first compilation takes a few hours and requires at least 10 GB of disk space.
First of all you need to install a few packages to your system.
Building OpenWrt requires a bunch of installed software.
If you are unsure about your system having all the dependencies installed, you can just go on with the OpenWrt compilation (see below) and, if it fails, check out the error messages.
On an Ubuntu system, the following command will install the minimum compilation dependencies:
--------------------------------------------------------------------------------
sudo apt update
sudo apt install --no-install-recommends git ca-certificates subversion wget make gcc g++ libncurses5-dev gawk unzip file patch python3-distutils python3-minimal python2-minimal libpython2-stdlib
--------------------------------------------------------------------------------
For other Linux distributions the packets list could be slightly different, check out the link:https://openwrt.org/docs/guide-developer/build-system/install-buildsystem[OpenWrt build system installation page].
Then you need to get the OpenWrt source code.
Make sure to _git clone_ the source code as normal user (i.e. do not use root): the compilation will refuse to run if the administrator user _root_ is being used.
.Download OpenWrt source code
LibreMesh can be built on top of various OpenWrt versions. We officially support the compilation with OpenWrt Old Stable (19.07.10) versions (LibreMesh still have to be adapted to work with the latest OpenWrt 21.02 version).
For compiling LibreMesh on top of the Old Stable version of OpenWrt:
--------------------------------------------------------------------------------
git clone -b v19.07.10 --single-branch https://git.openwrt.org/openwrt/openwrt.git
--------------------------------------------------------------------------------
.Enter OpenWrt build root
--------------------------------------------------------------------------------
cd openwrt
--------------------------------------------------------------------------------
.Take default OpenWrt repositories feeds
--------------------------------------------------------------------------------
cp feeds.conf.default feeds.conf
--------------------------------------------------------------------------------
.And add LibreMesh repositories to the OpenWrt feeds
--------------------------------------------------------------------------------
cat << EOF >> feeds.conf
src-git libremesh https://github.com/libremesh/lime-packages.git;v2020.4
src-git profiles https://github.com/libremesh/network-profiles.git
EOF
--------------------------------------------------------------------------------
With the lines above, you will compile the LibreMesh 2020.4 release. This is indicated by the `;v2020.4` suffix. Without this suffix, the `master` branch would be used, but **the `master` branch is *not* compatible with OpenWrt 19.07.** Instead, it is being developed for supporting OpenWrt 22.03.
.Update the packages from the feeds
--------------------------------------------------------------------------------
scripts/feeds update -a
scripts/feeds install -a
--------------------------------------------------------------------------------
.Run the configuration menu
--------------------------------------------------------------------------------
make menuconfig
--------------------------------------------------------------------------------
Check out the +target+ (e.g. +ATH79+), +subtarget+ (e.g. +generic+) and +profile+ (e.g. +tl-wdr3600-v1+) of your router on https://openwrt.org/toh/start[OpenWrt table of hardware].
Select the _Target System_, _Subtarget_ and _Target Profile_ accordingly.
**Deselect** erroneous feeds locations:
- Image configuration → Separate feed repositories → Enable feed libremesh
- Image configuration → Separate feed repositories → Enable feed profiles
**Deselect** problematic packages:
- Base system -> dnsmasq
- Network -> odhcpd-ipv6only
Optionally, **deselect** unused packages:
- Network -> ppp
If you local community has a profile in the https://github.com/libremesh/network-profiles/[network-profiles repository], you can select it in:
- LibreMesh -> network-profile -> profile-your_community-your_profile
[NOTE]
=========================
Network profiles are the specific configuration from the communities, and are stored in this collective
https://github.com/libremesh/network-profiles/[repository], but they can also be kept locally, depending on how every community network manages itself. For more instructions on how to create a profile or how to use a local one, check out the link:development-network_profiles.html[network profiles page].
=========================
**Select** (press space until when an asterisk `*` appears, like `<*>`) LibreMesh packages:
* LibreMesh (or LiMe) → Offline Documentation → lime-docs-minimal (LibreMesh minimal documentation)
* LibreMesh (or LiMe) → lime-app (LibreMeshApp)
* LibreMesh (or LiMe) → lime-hwd-openwrt-wan (Respect openwrt wan interface as default)
* LibreMesh (or LiMe) → lime-proto-anygw (LibreMesh anygw proto support)
* LibreMesh (or LiMe) → lime-proto-babeld (LibreMesh babeld proto support)
* LibreMesh (or LiMe) → lime-proto-batadv (LibreMesh batman-adv proto support)
* LibreMesh (or LiMe) → shared-state
** shared-state-babeld_hosts (babeld-hosts module for shared-state)
** shared-state-bat_hosts (bat-hosts module for shared-state)
** shared-state-nodes_and_links (nodes_and_links module for shared-state)
* Utilities -> babeld-auto-gw-mode
* Network -> batctl-default (B.A.T.M.A.N. Advanced user space configuration tool)
[NOTE]
=========================
If after the compilation you don't see the compiled image in the `bin/targets/.../.../` folder, it is possible that your router has such a small flash memory that the aforementioed packages don't fit in it (it can happen with routers having 4 MB of flash memory, check this on the https://openwrt.org/toh/start[OpenWrt Table of Hardware], or when selecting huge packages to be included). In this case, you can remove the `.config` generated packages list and repeat the packages selection without including `lime-app`. If the compiled image is still too large, try selecting only `lime-proto-anygw`, `lime-proto-batadv` and `lime-proto-babeld` or following https://openwrt.org/docs/guide-user/additional-software/saving_space[this guide].
=========================
Some more packages are recommended but not mandatory for a working LibreMesh network. Consider avoiding to select the following packages _only_ if the created image is too large and does not fit in the router memory.
- LibreMesh (or LiMe) -> check-date-http (Keep local date under NTP too far away skew)
- LibreMesh (or LiMe) -> Offline Documentation -> lime-docs (LibreMesh full documentation)
- LibreMesh (or LiMe) -> lime-hwd-ground-routing (Manage 802.1q VLANs for ground routing)
- LibreMesh (or LiMe) -> lime-debug (libremesh debug utils)
Additionally and optionally, httpS for the web interface can be enabled selecting (beware that the web interace will be shown as *not trusted*):
- Libraries -> libustream-wolfssl
- Utilities -> Encryption -> px5g-standalone
Finally, also the 802.11s mesh connections can be password protected, this will require a specific configuration and this package to be selected:
- Network -> wpad-mesh-wolfssl
and this to be **de**-selected:
- Network -> wpad-basic
[IMPORTANT]
=========================
Due to a link:https://bugs.openwrt.org/index.php?do=details&task_id=3441[known bug], can happen that wpad-mesh-wolfssl gets automatically deselected. **Each time you use menuconfig, please check if wpad-mesh-wolfssl is still selected.**
=========================
[NOTE]
=========================
In order to have additional packages, the easiest way is to select them in menuconfig. More packages can be installed afterwards via +opkg+, but some of these require a specific kernel configuration to be in place. This can be achieved following link:development-kernel_vermagic.html[these additional instructions dealing with kernel vermagic]. Beware that this will increase noticeably the time and storage space required for the compilation.
=========================
Save and exit.
At this stage there is the possibility to include custom files in the compiled firmware image. For this, you will have to create, inside the `openwrt/` directory, a `files/` directory containing the directory structure and files you want to add. For example, if you want to have a `/etc/config/lime-community` file you need to do the following:
-----------------------------
mkdir -p files/etc/config/
touch files/etc/config/lime-community
-----------------------------
and then edit the newly created `lime-community` file including your custom content. If a file from a package has the same name and path as a file in this directory, it will be overwritten. This is a quick way to include a custom configuration file, without the need to create an online link:development-network_profiles.html[network profile].
.Finally, compile the images
--------------------------------------------------------------------------------
make -j$(nproc)
--------------------------------------------------------------------------------
If everything goes well you should find the produced binaries inside the +bin/+ directory.
== Submitting Patches
We accept pull requests via GitHub. But patches can also be submitted via the lime-dev link:communication.html[mailing list].
== The Web Presence
The pages you're reading are generated from text files using the
http://www.methods.co.nz/asciidoc/[AsciiDoc] suite plus https://jekyllrb.com/[Jekyll].
Any changes made to https://github.com/libremesh/libremesh.github.io[the website repository] will be reflected on our `libremesh.org` website.
In order to generate these pages locally:
----
git clone https://github.com/libremesh/libremesh.github.io.git
cd libremesh.github.io && bundle install
bundle exec jekyll serve
----
For more details, check the https://github.com/libremesh/libremesh.github.io/blob/master/README.adoc[README] on Github.
If you would like to contribute to the documentation then please send patches to our mailing list or open a pull request on GitHub. An easy way to edit and file a pull request is clicking the "Edit this page" button at the top right of each page.
Please use the http://www.methods.co.nz/asciidoc/userguide.html[AsciiDoc syntax] for contributions on the web page.