diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 304 |
1 files changed, 201 insertions, 103 deletions
@@ -1,8 +1,28 @@ # Monero -Copyright (c) 2014-2018 The Monero Project. +Copyright (c) 2014-2019 The Monero Project. Portions Copyright (c) 2012-2013 The Cryptonote developers. +## Table of Contents + + - [Development resources](#development-resources) + - [Vulnerability response](#vulnerability-response) + - [Research](#research) + - [Announcements](#announcements) + - [Translations](#translations) + - [Build](#build) + - [IMPORTANT](#important) + - [Coverage](#coverage) + - [Introduction](#introduction) + - [About this project](#about-this-project) + - [Supporting the project](#supporting-the-project) + - [License](#license) + - [Contributing](#contributing) + - [Scheduled software upgrades](#scheduled-software-upgrades) + - [Release staging schedule and protocol](#release-staging-schedule-and-protocol) + - [Compiling Monero from source](#compiling-monero-from-source) + - [Dependencies](#dependencies) + ## Development resources - Web: [getmonero.org](https://getmonero.org) @@ -117,7 +137,7 @@ Monero uses a fixed-schedule software upgrade (hard fork) mechanism to implement Dates are provided in the format YYYY-MM-DD. -| Software upgrade block height | Date | Fork version | Minimum Monero version | Recommended Monero version | Details | +| Software upgrade block height | Date | Fork version | Minimum Monero version | Recommended Monero version | Details | | ------------------------------ | -----------| ----------------- | ---------------------- | -------------------------- | ---------------------------------------------------------------------------------- | | 1009827 | 2016-03-22 | v2 | v0.9.4 | v0.9.4 | Allow only >= ringsize 3, blocktime = 120 seconds, fee-free blocksize 60 kb | | 1141317 | 2016-09-21 | v3 | v0.9.4 | v0.10.0 | Splits coinbase into denominations | @@ -127,8 +147,8 @@ Dates are provided in the format YYYY-MM-DD. | 1546000 | 2018-04-06 | v7 | v0.12.0.0 | v0.12.3.0 | Cryptonight variant 1, ringsize >= 7, sorted inputs | 1685555 | 2018-10-18 | v8 | v0.13.0.0 | v0.13.0.4 | max transaction size at half the penalty free block size, bulletproofs enabled, cryptonight variant 2, fixed ringsize [11](https://youtu.be/KOO5S4vxi0o) | 1686275 | 2018-10-19 | v9 | v0.13.0.0 | v0.13.0.4 | bulletproofs required -| 1788000 | 2019-03-09 | v10 | v0.14.0.0 | v0.14.0.2 | New PoW based on Cryptonight-R, new block weight algorithm, slightly more efficient RingCT format -| 1788720 | 2019-03-10 | v11 | v0.14.0.0 | v0.14.0.2 | forbid old RingCT transaction format +| 1788000 | 2019-03-09 | v10 | v0.14.0.0 | v0.14.1.2 | New PoW based on Cryptonight-R, new block weight algorithm, slightly more efficient RingCT format +| 1788720 | 2019-03-10 | v11 | v0.14.0.0 | v0.14.1.2 | forbid old RingCT transaction format | XXXXXXX | 2019-10-XX | XX | XXXXXXXXX | XXXXXXXXX | X X's indicate that these details have not been determined as of commit date. @@ -206,9 +226,11 @@ invokes cmake commands as needed. * Install the dependencies * Change to the root of the source code directory, change to the most recent release branch, and build: - cd monero - git checkout release-v0.14 - make + ```bash + cd monero + git checkout release-v0.14 + make + ``` *Optional*: If your machine has several cores and enough memory, enable parallel build by running `make -j<number of threads>` instead of `make`. For @@ -232,23 +254,31 @@ invokes cmake commands as needed. * **Optional**: build and run the test suite to verify the binaries: - make release-test + ```bash + make release-test + ``` *NOTE*: `core_tests` test may take a few hours to complete. * **Optional**: to build binaries suitable for debugging: - make debug + ```bash + make debug + ``` * **Optional**: to build statically-linked binaries: - make release-static + ```bash + make release-static + ``` Dependencies need to be built with -fPIC. Static libraries usually aren't, so you may have to build them yourself with -fPIC. Refer to their documentation for how to build them. * **Optional**: build documentation in `doc/html` (omit `HAVE_DOT=YES` if `graphviz` is not installed): - HAVE_DOT=YES doxygen Doxyfile + ```bash + HAVE_DOT=YES doxygen Doxyfile + ``` #### On the Raspberry Pi @@ -259,24 +289,30 @@ Tested on a Raspberry Pi Zero with a clean install of minimal Raspbian Stretch ( * Install the dependencies for Monero from the 'Debian' column in the table above. * Increase the system swap size: -``` - sudo /etc/init.d/dphys-swapfile stop - sudo nano /etc/dphys-swapfile - CONF_SWAPSIZE=2048 - sudo /etc/init.d/dphys-swapfile start -``` + + ```bash + sudo /etc/init.d/dphys-swapfile stop + sudo nano /etc/dphys-swapfile + CONF_SWAPSIZE=2048 + sudo /etc/init.d/dphys-swapfile start + ``` + * If using an external hard disk without an external power supply, ensure it gets enough power to avoid hardware issues when syncing, by adding the line "max_usb_current=1" to /boot/config.txt * Clone monero and checkout the most recent release version: -``` - git clone https://github.com/monero-project/monero.git - cd monero - git checkout tags/v0.14.1.0 -``` + + ```bash + git clone https://github.com/monero-project/monero.git + cd monero + git checkout tags/v0.14.1.2 + ``` + * Build: -``` - make release -``` + + ```bash + make release + ``` + * Wait 4-6 hours * The resulting executables can be found in `build/release/bin` @@ -293,28 +329,33 @@ If you are using the older Raspbian Jessie image, compiling Monero is a bit more * As before, `apt-get update && apt-get upgrade` to install all of the latest software, and increase the system swap size -``` - sudo /etc/init.d/dphys-swapfile stop - sudo nano /etc/dphys-swapfile - CONF_SWAPSIZE=2048 - sudo /etc/init.d/dphys-swapfile start -``` + ```bash + sudo /etc/init.d/dphys-swapfile stop + sudo nano /etc/dphys-swapfile + CONF_SWAPSIZE=2048 + sudo /etc/init.d/dphys-swapfile start + ``` + * Then, install the dependencies for Monero except `libunwind` and `libboost-all-dev` * Install the latest version of boost (this may first require invoking `apt-get remove --purge libboost*` to remove a previous version if you're not using a clean install): -``` - cd - wget https://sourceforge.net/projects/boost/files/boost/1.64.0/boost_1_64_0.tar.bz2 - tar xvfo boost_1_64_0.tar.bz2 - cd boost_1_64_0 - ./bootstrap.sh - sudo ./b2 -``` + + ```bash + cd + wget https://sourceforge.net/projects/boost/files/boost/1.64.0/boost_1_64_0.tar.bz2 + tar xvfo boost_1_64_0.tar.bz2 + cd boost_1_64_0 + ./bootstrap.sh + sudo ./b2 + ``` + * Wait ~8 hours -``` - sudo ./bjam cxxflags=-fPIC cflags=-fPIC -a install -``` + + ```bash + sudo ./bjam cxxflags=-fPIC cflags=-fPIC -a install + ``` + * Wait ~4 hours * From here, follow the [general Raspberry Pi instructions](#on-the-raspberry-pi) from the "Clone monero and checkout most recent release version" step. @@ -333,24 +374,32 @@ application. * Open the MSYS shell via the `MSYS2 Shell` shortcut * Update packages using pacman: - pacman -Syu + ```bash + pacman -Syu + ``` * Exit the MSYS shell using Alt+F4 * Edit the properties for the `MSYS2 Shell` shortcut changing "msys2_shell.bat" to "msys2_shell.cmd -mingw64" for 64-bit builds or "msys2_shell.cmd -mingw32" for 32-bit builds * Restart MSYS shell via modified shortcut and update packages again using pacman: - pacman -Syu + ```bash + pacman -Syu + ``` * Install dependencies: To build for 64-bit Windows: - pacman -S mingw-w64-x86_64-toolchain make mingw-w64-x86_64-cmake mingw-w64-x86_64-boost mingw-w64-x86_64-openssl mingw-w64-x86_64-zeromq mingw-w64-x86_64-libsodium mingw-w64-x86_64-hidapi + ```bash + pacman -S mingw-w64-x86_64-toolchain make mingw-w64-x86_64-cmake mingw-w64-x86_64-boost mingw-w64-x86_64-openssl mingw-w64-x86_64-zeromq mingw-w64-x86_64-libsodium mingw-w64-x86_64-hidapi + ``` To build for 32-bit Windows: - pacman -S mingw-w64-i686-toolchain make mingw-w64-i686-cmake mingw-w64-i686-boost mingw-w64-i686-openssl mingw-w64-i686-zeromq mingw-w64-i686-libsodium mingw-w64-i686-hidapi + ```bash + pacman -S mingw-w64-i686-toolchain make mingw-w64-i686-cmake mingw-w64-i686-boost mingw-w64-i686-openssl mingw-w64-i686-zeromq mingw-w64-i686-libsodium mingw-w64-i686-hidapi + ``` * Open the MingW shell via `MinGW-w64-Win64 Shell` shortcut on 64-bit Windows or `MinGW-w64-Win64 Shell` shortcut on 32-bit Windows. Note that if you are @@ -360,35 +409,49 @@ application. * To git clone, run: - git clone --recursive https://github.com/monero-project/monero.git + ```bash + git clone --recursive https://github.com/monero-project/monero.git + ``` **Building** * Change to the cloned directory, run: - cd monero + ```bash + cd monero + ``` -* If you would like a specific [version/tag](https://github.com/monero-project/monero/tags), do a git checkout for that version. eg. 'v0.14.1.0'. If you don't care about the version and just want binaries from master, skip this step: +* If you would like a specific [version/tag](https://github.com/monero-project/monero/tags), do a git checkout for that version. eg. 'v0.14.1.2'. If you don't care about the version and just want binaries from master, skip this step: - git checkout v0.14.1.0 + ```bash + git checkout v0.14.1.2 + ``` * If you are on a 64-bit system, run: - make release-static-win64 + ```bash + make release-static-win64 + ``` * If you are on a 32-bit system, run: - make release-static-win32 + ```bash + make release-static-win32 + ``` * The resulting executables can be found in `build/release/bin` * **Optional**: to build Windows binaries suitable for debugging on a 64-bit system, run: - make debug-static-win64 + ```bash + make debug-static-win64 + ``` * **Optional**: to build Windows binaries suitable for debugging on a 32-bit system, run: - make debug-static-win32 + ```bash + make debug-static-win32 + ``` * The resulting executables can be found in `build/debug/bin` @@ -428,7 +491,7 @@ We assume you are compiling with a non-root user and you have `doas` enabled. Note: do not use the boost package provided by OpenBSD, as we are installing boost to `/usr/local`. -``` +```bash # Create boost building directory mkdir ~/boost cd ~/boost @@ -464,7 +527,7 @@ Build the cppzmq bindings. We assume you are compiling with a non-root user and you have `doas` enabled. -``` +```bash # Create cppzmq building directory mkdir ~/cppzmq cd ~/cppzmq @@ -484,7 +547,10 @@ cmake .. doas make install ``` -Build monero: `env DEVELOPER_LOCAL_TOOLS=1 BOOST_ROOT=/usr/local make release-static` +Build monero: +```bash +env DEVELOPER_LOCAL_TOOLS=1 BOOST_ROOT=/usr/local make release-static +``` #### OpenBSD >= 6.4 @@ -507,23 +573,27 @@ Then you need to increase the data ulimit size to 2GB and try again: `ulimit -d The default Solaris linker can't be used, you have to install GNU ld, then run cmake manually with the path to your copy of GNU ld: - mkdir -p build/release - cd build/release - cmake -DCMAKE_LINKER=/path/to/ld -D CMAKE_BUILD_TYPE=Release ../.. - cd ../.. +```bash +mkdir -p build/release +cd build/release +cmake -DCMAKE_LINKER=/path/to/ld -D CMAKE_BUILD_TYPE=Release ../.. +cd ../.. +``` Then you can run make as usual. ### On Linux for Android (using docker): - # Build image (for ARM 32-bit) - docker build -f utils/build_scripts/android32.Dockerfile -t monero-android . - # Build image (for ARM 64-bit) - docker build -f utils/build_scripts/android64.Dockerfile -t monero-android . - # Create container - docker create -it --name monero-android monero-android bash - # Get binaries - docker cp monero-android:/src/build/release/bin . +```bash +# Build image (for ARM 32-bit) +docker build -f utils/build_scripts/android32.Dockerfile -t monero-android . +# Build image (for ARM 64-bit) +docker build -f utils/build_scripts/android64.Dockerfile -t monero-android . +# Create container +docker create -it --name monero-android monero-android bash +# Get binaries +docker cp monero-android:/src/build/release/bin . +``` ### Building portable statically linked binaries @@ -542,12 +612,18 @@ By default, in either dynamically or statically linked builds, binaries target t You can also cross-compile static binaries on Linux for Windows and macOS with the `depends` system. * ```make depends target=x86_64-linux-gnu``` for 64-bit linux binaries. -* ```make depends target=x86_64-w64-mingw32``` for 64-bit windows binaries. Requires: python3 g++-mingw-w64-x86-64 wine1.6 bc -* ```make depends target=x86_64-apple-darwin11``` for macOS binaries. Requires: cmake imagemagick libcap-dev librsvg2-bin libz-dev libbz2-dev libtiff-tools python-dev -* ```make depends target=i686-linux-gnu``` for 32-bit linux binaries. Requires: g++-multilib bc -* ```make depends target=i686-w64-mingw32``` for 32-bit windows binaries. Requires: python3 g++-mingw-w64-i686 -* ```make depends target=arm-linux-gnueabihf``` for armv7 binaries. Requires: g++-arm-linux-gnueabihf -* ```make depends target=aarch64-linux-gnu``` for armv8 binaries. Requires: g++-aarch64-linux-gnu +* ```make depends target=x86_64-w64-mingw32``` for 64-bit windows binaries. + * Requires: `python3 g++-mingw-w64-x86-64 wine1.6 bc` +* ```make depends target=x86_64-apple-darwin11``` for macOS binaries. + * Requires: `cmake imagemagick libcap-dev librsvg2-bin libz-dev libbz2-dev libtiff-tools python-dev` +* ```make depends target=i686-linux-gnu``` for 32-bit linux binaries. + * Requires: `g++-multilib bc` +* ```make depends target=i686-w64-mingw32``` for 32-bit windows binaries. + * Requires: `python3 g++-mingw-w64-i686` +* ```make depends target=arm-linux-gnueabihf``` for armv7 binaries. + * Requires: `g++-arm-linux-gnueabihf` +* ```make depends target=aarch64-linux-gnu``` for armv8 binaries. + * Requires: `g++-aarch64-linux-gnu` The required packages are the names for each toolchain on apt. Depending on your distro, they may have different names. @@ -563,7 +639,9 @@ Packages are available for * Ubuntu and [snap supported](https://snapcraft.io/docs/core/install) systems, via a community contributed build. - snap install monero --beta + ```bash + snap install monero --beta + ``` Installing a snap is very quick. Snaps are secure. They are isolated with all of their dependencies. Snaps also auto update when a new version is released. @@ -573,25 +651,31 @@ Installing a snap is very quick. Snaps are secure. They are isolated with all of * Void Linux: - xbps-install -S monero + ```bash + xbps-install -S monero + ``` * GuixSD - guix package -i monero + ```bash + guix package -i monero + ``` * Docker - # Build using all available cores - docker build -t monero . - - # or build using a specific number of cores (reduce RAM requirement) - docker build --build-arg NPROC=1 -t monero . - - # either run in foreground - docker run -it -v /monero/chain:/root/.bitmonero -v /monero/wallet:/wallet -p 18080:18080 monero - - # or in background - docker run -it -d -v /monero/chain:/root/.bitmonero -v /monero/wallet:/wallet -p 18080:18080 monero + ```bash + # Build using all available cores + docker build -t monero . + + # or build using a specific number of cores (reduce RAM requirement) + docker build --build-arg NPROC=1 -t monero . + + # either run in foreground + docker run -it -v /monero/chain:/root/.bitmonero -v /monero/wallet:/wallet -p 18080:18080 monero + + # or in background + docker run -it -d -v /monero/chain:/root/.bitmonero -v /monero/wallet:/wallet -p 18080:18080 monero + ``` * The build needs 3 GB space. * Wait one hour or more @@ -604,7 +688,9 @@ The build places the binary in `bin/` sub-directory within the build directory from which cmake was invoked (repository root by default). To run in foreground: - ./bin/monerod +```bash +./bin/monerod +``` To list all available options, run `./bin/monerod --help`. Options can be specified either on the command line or in a configuration file passed by the @@ -614,7 +700,9 @@ of the argument without the leading dashes, for example `log-level=1`. To run in background: - ./bin/monerod --log-file monerod.log --detach +```bash +./bin/monerod --log-file monerod.log --detach +``` To run as a systemd service, copy [monerod.service](utils/systemd/monerod.service) to `/etc/systemd/system/` and @@ -662,7 +750,9 @@ setting the following configuration parameters and environment variables: Example command line to start monerod through Tor: - DNS_PUBLIC=tcp torsocks monerod --p2p-bind-ip 127.0.0.1 --no-igd +```bash +DNS_PUBLIC=tcp torsocks monerod --p2p-bind-ip 127.0.0.1 --no-igd +``` ### Using Tor on Tails @@ -670,9 +760,11 @@ TAILS ships with a very restrictive set of firewall rules. Therefore, you need to add a rule to allow this connection too, in addition to telling torsocks to allow inbound connections. Full example: - sudo iptables -I OUTPUT 2 -p tcp -d 127.0.0.1 -m tcp --dport 18081 -j ACCEPT - DNS_PUBLIC=tcp torsocks ./monerod --p2p-bind-ip 127.0.0.1 --no-igd --rpc-bind-ip 127.0.0.1 \ - --data-dir /home/amnesia/Persistent/your/directory/to/the/blockchain +```bash +sudo iptables -I OUTPUT 2 -p tcp -d 127.0.0.1 -m tcp --dport 18081 -j ACCEPT +DNS_PUBLIC=tcp torsocks ./monerod --p2p-bind-ip 127.0.0.1 --no-igd --rpc-bind-ip 127.0.0.1 \ + --data-dir /home/amnesia/Persistent/your/directory/to/the/blockchain +``` ## Debugging @@ -682,13 +774,13 @@ This section contains general instructions for debugging failed installs or prob We generally use the tool `gdb` (GNU debugger) to provide stack trace functionality, and `ulimit` to provide core dumps in builds which crash or segfault. -* To use gdb in order to obtain a stack trace for a build that has stalled: +* To use `gdb` in order to obtain a stack trace for a build that has stalled: Run the build. Once it stalls, enter the following command: -``` +```bash gdb /path/to/monerod `pidof monerod` ``` @@ -706,11 +798,13 @@ When it terminates with an output along the lines of "Segmentation fault (core d You can now analyse this core dump with `gdb` as follows: -`gdb /path/to/monerod /path/to/dumpfile` +```bash +gdb /path/to/monerod /path/to/dumpfile` +``` Print the stack trace with `bt` -* To run monero within gdb: +#### To run monero within gdb: Type `gdb /path/to/monerod` @@ -722,15 +816,17 @@ Type `run` to run monerod There are two tools available: -* ASAN +#### ASAN Configure Monero with the -D SANITIZE=ON cmake flag, eg: - cd build/debug && cmake -D SANITIZE=ON -D CMAKE_BUILD_TYPE=Debug ../.. +```bash +cd build/debug && cmake -D SANITIZE=ON -D CMAKE_BUILD_TYPE=Debug ../.. +``` You can then run the monero tools normally. Performance will typically halve. -* valgrind +#### valgrind Install valgrind and run as `valgrind /path/to/monerod`. It will be very slow. @@ -740,7 +836,9 @@ Instructions for debugging suspected blockchain corruption as per @HYC There is an `mdb_stat` command in the LMDB source that can print statistics about the database but it's not routinely built. This can be built with the following command: -`cd ~/monero/external/db_drivers/liblmdb && make` +```bash +cd ~/monero/external/db_drivers/liblmdb && make +``` The output of `mdb_stat -ea <path to blockchain dir>` will indicate inconsistencies in the blocks, block_heights and block_info table. |