updated installation page, added getting-started (#4734)
##### Summary Improvements on installation page and addition of a Getting Started page. I will add the Getting Started page to the html docs in another PR
Costa Tsaousis committed
Nov 25, 2018 at 16:23 UTC
147b51a591a572c6032c3cb8f7a2c020674203c7
3 files changed
+566
-314
doc/GettingStarted.md
new
+180
@@ -0,0 +1,180 @@
1
+# Getting Started
2
+
3
+These are your first steps **after** you have installed netdata. If you haven't installed it already, please check the [installation page](../installer).
4
+
5
+## Accessing the dashboard
6
+
7
+To access the netdata dashboard, navigate with your browser to:
8
+
9
+```
10
+http://your.server.ip:19999/
11
+```
12
+
13
+<details markdown="1"><summary>Click here, if it does not work.</summary>
14
+
15
+**Verify Netdata is running.**
16
+
17
+Open an ssh session to the server and execute `sudo ps -e | grep netdata`. It should respond with the PID of the netdata daemon. If it prints nothing, Netdata is not running. Check the [installation page](../installer) to install it.
18
+
19
+**Verify Netdata responds to HTTP requests.**
20
+
21
+Using the same ssh session, execute `curl -Ss http://localhost:19999`. It should dump on your screen the `index.html` page of the dashboard. If it does not, check the [installation page](../installer) to install it.
22
+
23
+**Verify Netdata receives the HTTP requests.**
24
+
25
+On the same ssh session, execute `tail -f /var/log/netdata/access.log` (if you installed the static 64bit package, use: `tail -f /opt/netdata/var/log/netdata/access.log`). This command will print on your screen all HTTP requests Netdata receives.
26
+
27
+Next, try to access the dashboard using your web browser, using the URL posted above. If nothing is printed on your terminal, the HTTP request is not routed to your Netdata.
28
+
29
+If you are not sure about your server IP, run this for a hint: `ip route get 8.8.8.8 | grep -oP " src [0-9\.]+ "`. It should print the IP of your server.
30
+
31
+If still Netdata does not receive the requests, something is blocking them. A firewall possibly. Please check your network.
32
+
33
+</details> <br/>
34
+
35
+When you install multiple Netdata servers, all your servers will appear at the `my-netdata` menu at the top left of the dashboard. For this to work, you have to manually access just once, the dashboard of each of your netdata servers.
36
+
37
+The `my-netdata` menu is more than just browser bookmarks. When switching Netdata servers from that menu, any settings of the current view are propagated to the other netdata server:
38
+
39
+- the current charts panning (drag the charts left or right),
40
+- the current charts zooming (`SHIFT` + mouse wheel over a chart),
41
+- the highlighted time-frame (`ALT` + select an area on a chart),
42
+- the scrolling position of the dashboard,
43
+- the theme you use,
44
+- etc.
45
+
46
+are all sent over to other netdata server, to allow you troubleshoot cross-server performance issues easily.
47
+
48
+## Starting and stopping Netdata
49
+
50
+Netdata installer integrates Netdata to your init / systemd environment.
51
+
52
+To start/stop Netdata, depending on your environment, you should use:
53
+
54
+- `systemctl start netdata` and `systemctl stop netdata`
55
+- `service netdata start` and `service netdata stop`
56
+- `/etc/init.d/netdata start` and `/etc/init.d/netdata stop`
57
+
58
+Once netdata is installed, the installer configures it to start at boot and stop at shutdown.
59
+
60
+For more information about using these commands, consult your system documentation.
61
+
62
+## Sizing Netdata
63
+
64
+The default installation of netdata is configured for a small round-robin database: just 1 hour of data. Depending on the memory your system has and the amount you can dedicate to Netdata, you should adapt this. On production systems with limited RAM, we suggest to set this to 3-4 hours. For best results you should set this to 24 or 48 hours.
65
+
66
+For every hour of data, Netdata needs about 25MB of RAM. If you can dedicate about 100MB of RAM to netdata, you should set its database size to 4 hours.
67
+
68
+To do this, edit `/etc/netdata/netdata.conf` (or `/opt/netdata/etc/netdata/netdata.conf`) and set:
69
+
70
+```
71
+[global]
72
+ history = SECONDS
73
+```
74
+
75
+Make sure the `history` line is not commented (comment lines start with `#`).
76
+
77
+1 hour is 3600 seconds, so the number you need to set is the result of `HOURS * 3600`.
78
+
79
+!!! danger
80
+ Be careful when you set this on production systems. If you set it too high, your system may run out of memory. By default, netdata is configured to be killed first when the system starves for memory, but better be careful to avoid issues.
81
+
82
+For more information about Netdata memory requirements, [check this page](../database).
83
+
84
+If your kernel supports KSM (most do), you can [enable KSM to half netdata memory requirement](../database#ksm).
85
+
86
+## Service discovery and auto-detection
87
+
88
+Netdata supports auto-detection of data collection sources. It auto-detects almost everything: database servers, web servers, dns server, etc.
89
+
90
+This auto-detection process happens **only once**, when netdata starts. To have Netdata re-discover data sources, you need to restart it. There are a few exceptions to this:
91
+
92
+- containers and VMs are auto-detected forever (when Netdata is running at the host).
93
+- many data sources are collected but are silenced by default, until there is useful information to collect (for example network interface dropped packet, will appear after a packet has been dropped).
94
+- services that are not optimal to collect on all systems, are disabled by default.
95
+- services we received feedback from users that caused issues when monitored, are also disabled by default (for example, `chrony` is disabled by default, because CentOS ships a version of it that uses 100% CPU when queried for statistics).
96
+
97
+Once a data collection source is detected, netdata will never quit trying to collect data from it, until Netdata is restarted. So, if you stop your web server, netdata will pick it up automatically when it is started again.
98
+
99
+Since Netdata is installed on all your systems (even inside containers), auto-detection is limited to `localhost`. This simplifies significantly the security model of a Netdata monitored infrastructure, since most applications allow `localhost` access by default.
100
+
101
+A few well known data collection sources that commonly need to be configured are:
102
+
103
+- [systemd services utilization](../collectors/cgroups.plugin/#monitoring-systemd-services) are not exposed by default on most systems, so `systemd` has to be configured to expose those metrics.
104
+
105
+## Configuration quick start
106
+
107
+In netdata we have:
108
+
109
+- **internal** data collection plugins (running inside the netdata daemon)
110
+- **external** data collection plugins (independent processes, sending data to netdata over pipes)
111
+- modular plugin **orchestrators** (external plugins that have multiple data collection modules)
112
+
113
+You can enable and disable plugins (internal and external) via `netdata.conf` at the section `[plugins]`.
114
+
115
+All plugins have dedicated sections in `netdata.conf`, like `[plugin:XXX]` for overwriting their default data collection frequency and providing additional command line options to them.
116
+
117
+All external plugins have their own `.conf` file.
118
+
119
+All modular plugin orchestrators have a directory in `/etc/netdata` with a `.conf` file for each of their modules.
120
+
121
+It is complex. So, let's see the whole configuration tree for the `nginx` module of `python.d.plugin`:
122
+
123
+In `netdata.conf` at the `[plugins]` section, `python.d.plugin` can be enabled or disabled:
124
+
125
+```
126
+[plugins]
127
+ python.d = yes
128
+```
129
+
130
+In `netdata.conf` at the `[plugin:python.d]` section, we can provide additional command line options for `python.d.plugin` and overwite its data collection frequency:
131
+
132
+```
133
+[plugin:python.d]
134
+ update every = 1
135
+ command options =
136
+```
137
+
138
+`python.d.plugin` has its own configuration file for enabling and disabling its modules (here you can disable `nginx` for example):
139
+
140
+```bash
141
+sudo /etc/netdata/edit-config python.d.conf
142
+```
143
+
144
+Then, `nginx` has its own configuration file for configuring its data collection jobs (most modules can collect data from multiple sources, so the `nginx` module can collect metrics from multiple, local or remote, `nginx` servers):
145
+
146
+```bash
147
+sudo /etc/netdata/edit-config python.d/nginx.conf
148
+```
149
+
150
+## Health monitoring and alarms
151
+
152
+Netdata ships hundreds of health monitoring alarms for detecting anomalies. These are optimized for production servers.
153
+
154
+Many users install netdata on workstations and are frustrated by the default alarms shipped with netdata. On these cases, we suggest to disable health monitoring.
155
+
156
+To disable it, edit `/etc/netdata/netdata.conf` (or `/opt/netdata/etc/netdata/netdata.conf` if you installed the static 64bit package) and set:
157
+
158
+```
159
+[health]
160
+ enabled = no
161
+```
162
+
163
+The above will disable health monitoring entirely.
164
+
165
+If you want to keep health monitoring enabled for the dashboard, but you want to disable email notifications, run this:
166
+
167
+```bash
168
+sudo /etc/netdata/edit-config health_alarm_notify.conf
169
+```
170
+
171
+and set `SEND_EMAIL="NO"`.
172
+
173
+(For static 64bit installations use `sudo /opt/netdata/etc/netdata/edit-config health_alarm_notify.conf`).
174
+
175
+## What is next?
176
+
177
+- Check [Data Collection](../collectors) for configuring data collection plugins.
178
+- Check [Health Monitoring](../health) for configuring your own alarms, or setting up alarm notifications.
179
+- Check [Streaming](../streaming) for centralizing netdata metrics.
180
+- Check [Backends](../backends) for long term archiving of netdata metrics to time-series databases.
htmldoc/buildyaml.sh
+29
@@ -72,6 +72,30 @@ markdown_extensions:
72
permalink: True
73
separator: "-"
74
- wikilinks
75
+ - pymdownx.arithmatex
76
+ - pymdownx.betterem:
77
+ smart_enable: all
78
+ - pymdownx.caret
79
+ - pymdownx.critic
80
+ - pymdownx.details
81
+ - pymdownx.emoji:
82
+ emoji_generator: !!python/name:pymdownx.emoji.to_svg
83
+ - pymdownx.inlinehilite
84
+ - pymdownx.magiclink
85
+ - pymdownx.mark
86
+ - pymdownx.smartsymbols
87
+ - pymdownx.superfences
88
+ - pymdownx.tasklist:
89
+ custom_checkbox: true
90
+ - pymdownx.tilde
91
+ - pymdownx.betterem
92
+ - pymdownx.superfences
93
+ - markdown.extensions.footnotes
94
+ - markdown.extensions.attr_list
95
+ - markdown.extensions.def_list
96
+ - markdown.extensions.tables
97
+ - markdown.extensions.abbr
98
+ - pymdownx.extrarawhtml
99
nav:'
100
101
navpart 1 . README "About"
@@ -91,6 +115,11 @@ echo -ne "- Installation:
115
- 'installer/UPDATE.md'
116
- 'installer/UNINSTALL.md'
117
"
118
+
119
+echo -ne "- Getting Started:
120
+ - 'doc/GettingStarted.md'
121
+"
122
+
123
echo -ne "- Running netdata:
124
"
125
navpart 2 daemon
installer/README.md
+357
-314
@@ -1,366 +1,409 @@
1
# Installation
2
-
2
4
-## Linux package managers
3
+Netdata is a **monitoring agent**. It is designed to be installed and run on all your systems: **physical** and **virtual** servers, **containers**, even **IoT**.
4
6
-You can install the latest release of netdata, using your package manager in
5
+The best way to install Netdata is directly from source. Our **automatic installer** will install any required system packages and compile Netdata directly on your systems.
6
8
- - Arch Linux (`sudo pacman -S netdata`)
9
- - Alpine Linux (`sudo apk add netdata`)
10
- - Debian Linux (`sudo apt install netdata`)
11
- - Gentoo Linux (`sudo emerge --ask netdata`)
12
- - OpenSUSE (`sudo zypper install netdata`)
13
- - Solus Linux (`sudo eopkg install netdata`)
14
- - Ubuntu Linux >= 18.04 (`sudo apt install netdata`)
7
+!!! warning
8
+ You can find Netdata packages distributed by third parties. In many cases, these packages are either too old or broken. So, the suggested ways to install Netdata are the ones in this page.
9
+ **We are currently working to provide our binary packages for all Linux distros.** Stay tuned...
10
16
-Please note that the particular packages are not build by netdata.
11
+1. [Automatic one line installation](#one-line-installation), easy installation from source, **this is the default**
12
+2. [Install pre-built static binary on any 64bit Linux](#linux-64bit-pre-built-static-binary)
13
+3. [Run Netdata in a docker container](#run-netdata-in-a-docker-container)
14
+4. [Manual installation, step by step](#install-netdata-on-linux-manually)
15
+5. [Install on FreeBSD](#freebsd)
16
+6. [Install on pfSense](#pfsense)
17
+7. [Enable on FreeNAS Corral](#freenas)
18
+8. [Install on macOS (OS X)](#macos)
19
18
-## Linux one liner
19
-
20
- 
21
-
22
-To install netdata from source to your systems and keep it up to date automatically, run the following:
23
-
24
-:hash:**`bash <(curl -Ss https://my-netdata.io/kickstart.sh)`**
25
-
26
-(do not `sudo` this command, it will do it by itself as needed)
27
-
28
-The command:
29
-
30
-1. detects the distro and **installs the required system packages** for building netdata (will ask for confirmation)
31
-2. downloads the latest netdata source tree to `/usr/src/netdata.git`.
32
-3. installs netdata by running `./netdata-installer.sh` from the source tree.
33
-4. installs `netdata-updater.sh` to `cron.daily`, so your netdata installation will be updated daily (you will get a message from cron only if the update fails).
34
-
35
-The `kickstart.sh` script passes all its parameters to `netdata-installer.sh`, so you can add more parameters to change the installation directory, enable/disable plugins, etc (check below).
36
-
37
-For automated installs, append a space + `--dont-wait` to the command line. You can also append `--dont-start-it` to prevent the installer from starting netdata. Example:
38
-
39
-```sh
40
-bash <(curl -Ss https://my-netdata.io/kickstart.sh) all --dont-wait --dont-start-it
41
-```
42
-
43
-## Linux 64bit pre-built static binary
44
-
45
-You can install a pre-compiled static binary of netdata for any Intel/AMD 64bit Linux system (even those that don't have a package manager, like CoreOS, CirrOS, busybox systems, etc). You can also use these packages on systems with broken or unsupported package managers.
46
-
47
-<br/> 
48
-
49
-To install netdata with a binary package on any Linux distro, any kernel version - for **Intel/AMD 64bit** hosts, run the following:
50
-
51
-:hash: **`bash <(curl -Ss https://my-netdata.io/kickstart-static64.sh)`**
52
-
53
-(do not `sudo` this command, it will do it by itself as needed; the target system does not need `bash` installed, check below for instructions to run it without `bash`)
54
-
55
-*Note: The static builds install netdata at `/opt/netdata`*
56
-
57
-For automated installs, append a space + `--dont-wait` to the command line. You can also append `--dont-start-it` to prevent the installer from starting netdata. Example:
58
-
59
-```sh
60
-bash <(curl -Ss https://my-netdata.io/kickstart-static64.sh) --dont-wait --dont-start-it
61
-```
62
-
63
-If your shell fails to handle the above one liner, do this:
64
-
65
-```sh
66
-# download the script with curl
67
-curl https://my-netdata.io/kickstart-static64.sh >/tmp/kickstart-static64.sh
68
-
69
-# or, download the script with wget
70
-wget -O /tmp/kickstart-static64.sh https://my-netdata.io/kickstart-static64.sh
71
-
72
-# run the downloaded script (any sh is fine, no need for bash)
73
-sh /tmp/kickstart-static64.sh
74
-```
75
-
76
-The static binary files are kept in repo [binary-packages](https://github.com/netdata/binary-packages). You can download any of the `.run` files, and run it. These files are self-extracting shell scripts built with [makeself](https://github.com/megastep/makeself). The target system does **not** need to have bash installed. The same files can be used for updates too.
77
-
78
-## Docker
79
-
80
-You can [Install netdata with Docker](../docker/#install-netdata-with-docker)
81
-
82
-## Other installation methods
83
-
84
-- **Linux manual installation from source**
85
-
86
- Semi-automatic, with more details about the steps involved and actions taken [here](#install-netdata-on-linux-manually)
87
-
88
-- **Non-Linux installation**
89
- - [Install from package or source, on FreeBSD](#freebsd)
90
- - [Install from package, on pfSense](#pfsense)
91
- - [Enable netdata on FreeNAS Corral](#freenas)
92
- - [Install from package or source, on macOS (OS X)](#macos)
93
-
94
- See also the list of netdata [package maintainers](../packaging/maintainers) for ASUSTOR NAS, OpenWRT, ReadyNAS, etc.
95
-
96
-## Install netdata on Linux manually
97
-
98
-To install the latest git version of netdata, please follow these 2 steps:
99
-
100
-1. [Prepare your system](#prepare-your-system)
101
-
102
- Install the required packages on your system.
103
-
104
-2. [Install netdata](#install-netdata)
105
-
106
- Download and install netdata. You can also update it the same way.
20
+See also the list of Netdata [package maintainers](../packaging/maintainers) for ASUSTOR NAS, OpenWRT, ReadyNAS, etc.
21
22
---
23
110
-### Prepare your system
24
+## One line installation
25
112
-Try our experimental automatic requirements installer (no need to be root). This will try to find the packages that should be installed on your system to build and run netdata. It supports most major Linux distributions released after 2010:
26
+> This method is **fully automatic on all Linux** distributions. FreeBSD and MacOS systems need some preparations before installing Netdata for the first time. Check the [FreeBSD](#freebsd) and the [MacOS](#macos) sections for more information.
27
114
-- **Alpine** Linux and its derivatives (you have to install `bash` yourself, before using the installer)
115
-- **Arch** Linux and its derivatives
116
-- **Gentoo** Linux and its derivatives
117
-- **Debian** Linux and its derivatives (including **Ubuntu**, **Mint**)
118
-- **Fedora** and its derivatives (including **Red Hat Enterprise Linux**, **CentOS**, **Amazon Machine Image**)
119
-- **SuSe** Linux and its derivatives (including **openSuSe**)
120
-- **SLE12** Must have your system registered with Suse Customer Center or have the DVD. See [#1162](https://github.com/netdata/netdata/issues/1162)
28
+To install Netdata from source and keep it up to date automatically, run the following:
29
122
-Install the packages for having a **basic netdata installation** (system monitoring and many applications, without `mysql` / `mariadb`, `postgres`, `named`, hardware sensors and `SNMP`):
123
-
124
-```sh
125
-curl -Ss 'https://raw.githubusercontent.com/netdata/netdata-demo-site/master/install-required-packages.sh' >/tmp/kickstart.sh && bash /tmp/kickstart.sh -i netdata
126
-```
127
-
128
-Install all the required packages for **monitoring everything netdata can monitor**:
129
-
130
-```sh
131
-curl -Ss 'https://raw.githubusercontent.com/netdata/netdata-demo-site/master/install-required-packages.sh' >/tmp/kickstart.sh && bash /tmp/kickstart.sh -i netdata-all
30
+```bash
31
+bash <(curl -Ss https://my-netdata.io/kickstart.sh)
32
```
33
134
-If the above do not work for you, please [open a github issue](https://github.com/netdata/netdata/issues/new?title=packages%20installer%20failed&labels=installation%20help&body=The%20experimental%20packages%20installer%20failed.%0A%0AThis%20is%20what%20it%20says:%0A%0A%60%60%60txt%0A%0Aplease%20paste%20your%20screen%20here%0A%0A%60%60%60) with a copy of the message you get on screen. We are trying to make it work everywhere (this is also why the script [reports back](https://github.com/netdata/netdata/issues/2054) success or failure for all its runs).
135
-
136
----
137
-
138
-This is how to do it by hand:
34
+*(do not `sudo` this command, it will do it by itself as needed)*
35
140
-```sh
141
-# Debian / Ubuntu
142
-apt-get install zlib1g-dev uuid-dev libmnl-dev gcc make git autoconf autoconf-archive autogen automake pkg-config curl
36
+ 
37
144
-# Fedora
145
-dnf install zlib-devel libuuid-devel libmnl-devel gcc make git autoconf autoconf-archive autogen automake pkgconfig curl findutils
38
+<details markdown="1"><summary>Click here for more information and advanced use of this command.</summary>
39
147
-# CentOS / Red Hat Enterprise Linux
148
-yum install autoconf automake curl gcc git libmnl-devel libuuid-devel lm_sensors make MySQL-python nc pkgconfig python python-psycopg2 PyYAML zlib-devel
40
+ <br/>
41
+Verify the integrity of the script with this:
42
43
+```bash
44
+[ "6c15b7d7d31dc130631c42da65df71ae" = "$(curl -Ss https://my-netdata.io/kickstart.sh | md5sum | cut -d ' ' -f 1)" ] && echo "OK, VALID" || echo "FAILED, INVALID"
45
```
151
-
152
-Please note that for RHEL/CentOS you might need [EPEL](http://www.tecmint.com/how-to-enable-epel-repository-for-rhel-centos-6-5/).
153
-
154
-Once netdata is compiled, to run it the following packages are required (already installed using the above commands):
155
-
156
-package|description
157
-:-----:|-----------
158
-`libuuid`|part of `util-linux` for GUIDs management
159
-`zlib`|gzip compression for the internal netdata web server
160
-
161
-*netdata will fail to start without the above.*
162
-
163
-netdata plugins and various aspects of netdata can be enabled or benefit when these are installed (they are optional):
164
-
165
-package|description
166
-:-----:|-----------
167
-`bash`|for shell plugins and **alarm notifications**
168
-`curl`|for shell plugins and **alarm notifications**
169
-`iproute` or `iproute2`|for monitoring **Linux traffic QoS**<br/>use `iproute2` if `iproute` reports as not available or obsolete
170
-`python`|for most of the external plugins
171
-`python-yaml`|used for monitoring **beanstalkd**
172
-`python-beanstalkc`|used for monitoring **beanstalkd**
173
-`python-dnspython`|used for monitoring DNS query time
174
-`python-ipaddress`|used for monitoring **DHCPd**<br/>this package is required only if the system has python v2. python v3 has this functionality embedded
175
-`python-mysqldb`<br/>or<br/>`python-pymysql`|used for monitoring **mysql** or **mariadb** databases<br/>`python-mysqldb` is a lot faster and thus preferred
176
-`python-psycopg2`|used for monitoring **postgresql** databases
177
-`python-pymongo`|used for monitoring **mongodb** databases
178
-`nodejs`|used for `node.js` plugins for monitoring **named** and **SNMP** devices
179
-`lm-sensors`|for monitoring **hardware sensors**
180
-`libmnl`|for collecting netfilter metrics
181
-`netcat`|for shell plugins to collect metrics from remote systems
182
-
183
-*netdata will greatly benefit if you have the above packages installed, but it will still work without them.*
184
-
185
----
186
-
187
-### Install netdata
188
-
189
-Do this to install and run netdata:
190
-
191
-```sh
192
-
193
-# download it - the directory 'netdata' will be created
194
-git clone https://github.com/netdata/netdata.git --depth=1
195
-cd netdata
196
-
197
-# run script with root privileges to build, install, start netdata
198
-./netdata-installer.sh
199
-
46
+*It should print `OK, VALID` if the script is the one we ship.*
47
+
48
+The `kickstart.sh` script:
49
+
50
+- detects the Linux distro and **installs the required system packages** for building Netdata (will ask for confirmation)
51
+- downloads the latest Netdata source tree to `/usr/src/netdata.git`.
52
+- installs Netdata by running `./netdata-installer.sh` from the source tree.
53
+- installs `netdata-updater.sh` to `cron.daily`, so your Netdata installation will be updated daily (you will get a message from cron only if the update fails).
54
+- For QA purposes, this installation method lets us know if it succeed or failed.
55
+
56
+The `kickstart.sh` script passes all its parameters to `netdata-installer.sh`, so you can add more parameters to change the installation directory, enable/disable plugins, etc (check below).
57
+
58
+For automated installs, append a space + `--dont-wait` to the command line. You can also append `--dont-start-it` to prevent the installer from starting Netdata. Example:
59
+
60
+```bash
61
+ bash <(curl -Ss https://my-netdata.io/kickstart.sh) --dont-wait --dont-start-it
62
```
63
202
-* If you don't want to run it straight-away, add `--dont-start-it` option.
203
-
204
-* If you don't want to install it on the default directories, you can run the installer like this: `./netdata-installer.sh --install /opt`. This one will install netdata in `/opt/netdata`.
205
-
206
-Once the installer completes, the file `/etc/netdata/netdata.conf` will be created (if you changed the installation directory, the configuration will appear in that directory too).
207
-
208
-You can edit this file to set options. One common option to tweak is `history`, which controls the size of the memory database netdata will use. By default is `3600` seconds (an hour of data at the charts) which makes netdata use about 10-15MB of RAM (depending on the number of charts detected on your system). Check **[[Memory Requirements]]**.
64
+</details> <br/>
65
210
-To apply the changes you made, you have to restart netdata.
66
+Once Netdata is installed, see [Getting Started](../doc/GettingStarted.md).
67
68
---
69
214
-## Other Systems
215
-
216
-
217
-
218
-##### FreeBSD
219
-
220
-You can install netdata from ports or packages collection.
221
-
222
-This is how to install the latest netdata version from sources on FreeBSD:
223
-
224
-```sh
225
-# install required packages
226
-pkg install bash e2fsprogs-libuuid git curl autoconf automake pkgconf pidof
227
-
228
-# download netdata
229
-git clone https://github.com/netdata/netdata.git --depth=1
230
-
231
-# install netdata in /opt/netdata
232
-cd netdata
233
-./netdata-installer.sh --install /opt
234
-```
235
-
236
-##### pfSense
237
-To install netdata on pfSense run the following commands (within a shell or under Diagnostics/Command Prompt within the pfSense web interface).
238
-
239
-Change platform (i386/amd64, etc) and FreeBSD versions (10/11, etc) according to your environment and change netdata version (1.10.0 in example) according to latest version present within the FreeSBD repository:-
240
-
241
-Note first three packages are downloaded from the pfSense repository for maintaining compatibility with pfSense, netdata is downloaded from the FreeBSD repository.
242
-```
243
-pkg install pkgconf
244
-pkg install bash
245
-pkg install e2fsprogs-libuuid
246
-pkg add http://pkg.freebsd.org/FreeBSD:11:amd64/latest/All/netdata-1.11.0.txz
247
-```
248
-To start netdata manually run `service netdata onestart`
249
-
250
-To start netdata automatically at each boot add `service netdata start` as a Shellcmd within the pfSense web interface (under **Services/Shellcmd**, which you need to install beforehand under **System/Package Manager/Available Packages**).
251
-Shellcmd Type should be set to `Shellcmd`.
252
-
253
-Alternatively more information can be found in https://doc.pfsense.org/index.php/Installing_FreeBSD_Packages, for achieving the same via the command line and scripts.
70
+## Linux 64bit pre-built static binary
71
255
-If you experience an issue with `/usr/bin/install` absense on pfSense 2.3 or earlier, update pfSense or use workaround from [https://redmine.pfsense.org/issues/6643](https://redmine.pfsense.org/issues/6643)
72
+You can install a pre-compiled static binary of Netdata on any Intel/AMD 64bit Linux system
73
+(even those that don't have a package manager, like CoreOS, CirrOS, busybox systems, etc).
74
+You can also use these packages on systems with broken or unsupported package managers.
75
257
-##### FreeNAS
258
-On FreeNAS-Corral-RELEASE (>=10.0.3), netdata is pre-installed.
76
+To install Netdata with a binary package on any Linux distro, any kernel version - for **Intel/AMD 64bit** hosts, run the following:
77
+
78
+```bash
79
260
-To use netdata, the service will need to be enabled and started from the FreeNAS **[CLI](https://github.com/freenas/cli)**.
80
+ bash <(curl -Ss https://my-netdata.io/kickstart-static64.sh)
81
262
-To enable the netdata service:
263
-```
264
-service netdata config set enable=true
82
```
83
267
-To start the netdata service:
268
-```
269
-service netdata start
270
-```
271
-
272
-##### macOS
84
+*(do not `sudo` this command, it will do it by itself as needed; if the target system does not have `bash` installed, see below for instructions to run it without `bash`)*
85
274
-netdata on macOS still has limited charts, but external plugins do work.
86
+ 
87
276
-You can either install netdata with [Homebrew](https://brew.sh/)
88
+> The static builds install Netdata at **`/opt/netdata`**
89
278
-```sh
279
-brew install netdata
280
-```
90
+<details markdown="1"><summary>Click here for more information and advanced use of this command.</summary>
91
282
-or from source:
92
+ <br/>
93
+Verify the integrity of the script with this:
94
284
-```sh
285
-# install Xcode Command Line Tools
286
-xcode-select --install
95
+```bash
96
+[ "a5c16b3126b696ff7b4c8d8d8dc6957d" = "$(curl -Ss https://my-netdata.io/kickstart-static64.sh | md5sum | cut -d ' ' -f 1)" ] && echo "OK, VALID" || echo "FAILED, INVALID"
97
```
288
-click `Install` in the software update popup window, then
289
-```sh
290
-# install HomeBrew package manager
291
-/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
98
293
-# install required packages
294
-brew install ossp-uuid autoconf automake pkg-config
99
+*It should print `OK, VALID` if the script is the one we ship.*
100
296
-# download netdata
297
-git clone https://github.com/netdata/netdata.git --depth=1
101
+For automated installs, append a space + `--dont-wait` to the command line. You can also append `--dont-start-it` to prevent the installer from starting Netdata.
102
+
103
+Example:
104
+
105
+```bash
106
299
-# install netdata in /usr/local/netdata
300
-cd netdata
301
-sudo ./netdata-installer.sh --install /usr/local
302
-```
303
-
304
-The installer will also install a startup plist to start netdata when your Mac boots.
305
-
306
-##### Alpine 3.x
307
-
308
-Execute these commands to install netdata in Alpine Linux 3.x:
107
+ bash <(curl -Ss https://my-netdata.io/kickstart-static64.sh) --dont-wait --dont-start-it
108
109
```
311
-# install required packages
312
-apk add alpine-sdk bash curl zlib-dev util-linux-dev libmnl-dev gcc make git autoconf automake pkgconfig python logrotate
313
-
314
-# if you plan to run node.js netdata plugins
315
-apk add nodejs
316
-
317
-# download netdata - the directory 'netdata' will be created
318
-git clone https://github.com/netdata/netdata.git --depth=1
319
-cd netdata
110
321
-
322
-# build it, install it, start it
323
-./netdata-installer.sh
324
-
325
-
326
-# make netdata start at boot
327
-echo -e "#!/usr/bin/env bash\n/usr/sbin/netdata" >/etc/local.d/netdata.start
328
-chmod 755 /etc/local.d/netdata.start
329
-
330
-# make netdata stop at shutdown
331
-echo -e "#!/usr/bin/env bash\nkillall netdata" >/etc/local.d/netdata.stop
332
-chmod 755 /etc/local.d/netdata.stop
333
-
334
-# enable the local service to start automatically
335
-rc-update add local
111
+If your shell fails to handle the above one liner, do this:
112
+
113
+```bash
114
+# download the script with curl
115
+curl https://my-netdata.io/kickstart-static64.sh >/tmp/kickstart-static64.sh
116
+
117
+# or, download the script with wget
118
+wget -O /tmp/kickstart-static64.sh https://my-netdata.io/kickstart-static64.sh
119
+
120
+# run the downloaded script (any sh is fine, no need for bash)
121
+sh /tmp/kickstart-static64.sh
122
```
123
338
-##### Synology
339
-
340
-The documentation previously recommended installing the Debian Chroot package from the Synology community package sources and then running netdata from within the chroot. This does not work, as the chroot environment does not have access to `/proc`, and therefore exposes very few metrics to netdata. Additionally, [this issue](https://github.com/SynoCommunity/spksrc/issues/2758), still open as of 2018/06/24, indicates that the Debian Chroot package is not suitable for DSM versions greater than version 5 and may corrupt system libraries and render the NAS unable to boot.
341
-
342
-The good news is that the 64-bit static installer works fine if your NAS is one that uses the amd64 architecture. It will install the content into `/opt/netdata`, making future removal safe and simple.
124
+- The static binary files are kept in repo [binary-packages](https://github.com/netdata/binary-packages). You can download any of the `.run` files, and run it. These files are self-extracting shell scripts built with [makeself](https://github.com/megastep/makeself).
125
+- The target system does **not** need to have bash installed.
126
+- The same files can be used for updates too.
127
+- For QA purposes, this installation method lets us know if it succeed or failed.
128
344
-###### Additional Work
129
+</details> <br/>
130
346
-When netdata is first installed, it will run as _root_. This may or may not be acceptable for you, and since other installations run it as the _netdata_ user, you might wish to do the same. This requires some extra work:
131
+Once Netdata is installed, see [Getting Started](../doc/GettingStarted.md).
132
348
-1. Creat a group `netdata` via the Synology group interface. Give it no access to anything.
349
-2. Create a user `netdata` via the Synology user interface. Give it no access to anything and a random password. Assign the user to the `netdata` group. Netdata will chuid to this user when running.
350
-3. Change ownership of the following directories, as defined in [Netdata Security](../doc/netdata-security.md#security-design):
351
-
352
-```
353
-$ chown -R root:netdata /opt/netdata/usr/share/netdata
354
-$ chown -R netdata:netdata /opt/netdata/var/lib/netdata /opt/netdata/var/cache/netdata
355
-$ chown -R netdata:root /opt/netdata/var/log/netdata
356
-```
133
+---
134
358
-Additionally, as of 2018/06/24, the netdata installer doesn't recognize DSM as an operating system, so no init script is installed. You'll have to do this manually:
135
+## Run Netdata in a Docker container
136
+
137
+You can [Install Netdata with Docker](../docker/#install-netdata-with-docker).
138
360
-1. Add [this file](https://gist.github.com/oskapt/055d474d7bfef32c49469c1b53e8225f) as `/etc/rc.netdata`. Make it executable with `chmod 0755 /etc/rc.netdata`.
361
-2. Edit `/etc/rc.local` and add a line calling `/etc/rc.netdata` to have it start on boot:
139
+---
140
363
-```
364
-# Netdata startup
365
-[ -x /etc/rc.netdata ] && /etc/rc.netdata start
141
+## Install Netdata on Linux manually
142
+
143
+To install the latest git version of Netdata, please follow these 2 steps:
144
+
145
+1. [Prepare your system](#prepare-your-system)
146
+
147
+ Install the required packages on your system.
148
+
149
+2. [Install Netdata](#install-netdata)
150
+
151
+ Download and install Netdata. You can also update it the same way.
152
+
153
+---
154
+
155
+### Prepare your system
156
+
157
+Try our experimental automatic requirements installer (no need to be root). This will try to find the packages that should be installed on your system to build and run Netdata. It supports most major Linux distributions released after 2010:
158
+
159
+- **Alpine** Linux and its derivatives (you have to install `bash` yourself, before using the installer)
160
+- **Arch** Linux and its derivatives
161
+- **Gentoo** Linux and its derivatives
162
+- **Debian** Linux and its derivatives (including **Ubuntu**, **Mint**)
163
+- **Fedora** and its derivatives (including **Red Hat Enterprise Linux**, **CentOS**, **Amazon Machine Image**)
164
+- **SuSe** Linux and its derivatives (including **openSuSe**)
165
+- **SLE12** Must have your system registered with Suse Customer Center or have the DVD. See [#1162](https://github.com/netdata/netdata/issues/1162)
166
+
167
+Install the packages for having a **basic Netdata installation** (system monitoring and many applications, without `mysql` / `mariadb`, `postgres`, `named`, hardware sensors and `SNMP`):
168
+
169
+```sh
170
+curl -Ss 'https://raw.githubusercontent.com/netdata/netdata-demo-site/master/install-required-packages.sh' >/tmp/kickstart.sh && bash /tmp/kickstart.sh -i netdata
171
+```
172
+
173
+Install all the required packages for **monitoring everything Netdata can monitor**:
174
+
175
+```sh
176
+curl -Ss 'https://raw.githubusercontent.com/netdata/netdata-demo-site/master/install-required-packages.sh' >/tmp/kickstart.sh && bash /tmp/kickstart.sh -i netdata-all
177
+```
178
+
179
+If the above do not work for you, please [open a github issue](https://github.com/netdata/netdata/issues/new?title=packages%20installer%20failed&labels=installation%20help&body=The%20experimental%20packages%20installer%20failed.%0A%0AThis%20is%20what%20it%20says:%0A%0A%60%60%60txt%0A%0Aplease%20paste%20your%20screen%20here%0A%0A%60%60%60) with a copy of the message you get on screen. We are trying to make it work everywhere (this is also why the script [reports back](https://github.com/netdata/netdata/issues/2054) success or failure for all its runs).
180
+
181
+---
182
+
183
+This is how to do it by hand:
184
+
185
+```sh
186
+# Debian / Ubuntu
187
+apt-get install zlib1g-dev uuid-dev libmnl-dev gcc make git autoconf autoconf-archive autogen automake pkg-config curl
188
+
189
+# Fedora
190
+dnf install zlib-devel libuuid-devel libmnl-devel gcc make git autoconf autoconf-archive autogen automake pkgconfig curl findutils
191
+
192
+# CentOS / Red Hat Enterprise Linux
193
+yum install autoconf automake curl gcc git libmnl-devel libuuid-devel lm_sensors make MySQL-python nc pkgconfig python python-psycopg2 PyYAML zlib-devel
194
+
195
+```
196
+
197
+Please note that for RHEL/CentOS you might need [EPEL](http://www.tecmint.com/how-to-enable-epel-repository-for-rhel-centos-6-5/).
198
+
199
+Once Netdata is compiled, to run it the following packages are required (already installed using the above commands):
200
+
201
+package|description
202
+:-----:|-----------
203
+`libuuid`|part of `util-linux` for GUIDs management
204
+`zlib`|gzip compression for the internal Netdata web server
205
+
206
+*Netdata will fail to start without the above.*
207
+
208
+Netdata plugins and various aspects of Netdata can be enabled or benefit when these are installed (they are optional):
209
+
210
+package|description
211
+:-----:|-----------
212
+`bash`|for shell plugins and **alarm notifications**
213
+`curl`|for shell plugins and **alarm notifications**
214
+`iproute` or `iproute2`|for monitoring **Linux traffic QoS**<br/>use `iproute2` if `iproute` reports as not available or obsolete
215
+`python`|for most of the external plugins
216
+`python-yaml`|used for monitoring **beanstalkd**
217
+`python-beanstalkc`|used for monitoring **beanstalkd**
218
+`python-dnspython`|used for monitoring DNS query time
219
+`python-ipaddress`|used for monitoring **DHCPd**<br/>this package is required only if the system has python v2. python v3 has this functionality embedded
220
+`python-mysqldb`<br/>or<br/>`python-pymysql`|used for monitoring **mysql** or **mariadb** databases<br/>`python-mysqldb` is a lot faster and thus preferred
221
+`python-psycopg2`|used for monitoring **postgresql** databases
222
+`python-pymongo`|used for monitoring **mongodb** databases
223
+`nodejs`|used for `node.js` plugins for monitoring **named** and **SNMP** devices
224
+`lm-sensors`|for monitoring **hardware sensors**
225
+`libmnl`|for collecting netfilter metrics
226
+`netcat`|for shell plugins to collect metrics from remote systems
227
+
228
+*Netdata will greatly benefit if you have the above packages installed, but it will still work without them.*
229
+
230
+---
231
+
232
+### Install Netdata
233
+
234
+Do this to install and run Netdata:
235
+
236
+```sh
237
+
238
+# download it - the directory 'netdata' will be created
239
+git clone https://github.com/netdata/netdata.git --depth=1
240
+cd netdata
241
+
242
+# run script with root privileges to build, install, start Netdata
243
+./netdata-installer.sh
244
+
245
+```
246
+
247
+* If you don't want to run it straight-away, add `--dont-start-it` option.
248
+
249
+* If you don't want to install it on the default directories, you can run the installer like this: `./netdata-installer.sh --install /opt`. This one will install Netdata in `/opt/netdata`.
250
+
251
+Once the installer completes, the file `/etc/netdata/netdata.conf` will be created (if you changed the installation directory, the configuration will appear in that directory too).
252
+
253
+You can edit this file to set options. One common option to tweak is `history`, which controls the size of the memory database Netdata will use. By default is `3600` seconds (an hour of data at the charts) which makes Netdata use about 10-15MB of RAM (depending on the number of charts detected on your system). Check **[[Memory Requirements]]**.
254
+
255
+To apply the changes you made, you have to restart Netdata.
256
+
257
+---
258
+
259
+## Other Systems
260
+
261
+
262
+
263
+##### FreeBSD
264
+
265
+You can install Netdata from ports or packages collection.
266
+
267
+This is how to install the latest Netdata version from sources on FreeBSD:
268
+
269
+```sh
270
+# install required packages
271
+pkg install bash e2fsprogs-libuuid git curl autoconf automake pkgconf pidof
272
+
273
+# download Netdata
274
+git clone https://github.com/netdata/netdata.git --depth=1
275
+
276
+# install Netdata in /opt/netdata
277
+cd netdata
278
+./netdata-installer.sh --install /opt
279
+```
280
+
281
+##### pfSense
282
+To install Netdata on pfSense run the following commands (within a shell or under Diagnostics/Command Prompt within the pfSense web interface).
283
+
284
+Change platform (i386/amd64, etc) and FreeBSD versions (10/11, etc) according to your environment and change Netdata version (1.10.0 in example) according to latest version present within the FreeSBD repository:-
285
+
286
+Note first three packages are downloaded from the pfSense repository for maintaining compatibility with pfSense, Netdata is downloaded from the FreeBSD repository.
287
+```
288
+pkg install pkgconf
289
+pkg install bash
290
+pkg install e2fsprogs-libuuid
291
+pkg add http://pkg.freebsd.org/FreeBSD:11:amd64/latest/All/netdata-1.11.0.txz
292
+```
293
+To start Netdata manually run `service netdata onestart`
294
+
295
+To start Netdata automatically at each boot add `service netdata start` as a Shellcmd within the pfSense web interface (under **Services/Shellcmd**, which you need to install beforehand under **System/Package Manager/Available Packages**).
296
+Shellcmd Type should be set to `Shellcmd`.
297
+
298
+Alternatively more information can be found in https://doc.pfsense.org/index.php/Installing_FreeBSD_Packages, for achieving the same via the command line and scripts.
299
+
300
+If you experience an issue with `/usr/bin/install` absense on pfSense 2.3 or earlier, update pfSense or use workaround from [https://redmine.pfsense.org/issues/6643](https://redmine.pfsense.org/issues/6643)
301
+
302
+##### FreeNAS
303
+On FreeNAS-Corral-RELEASE (>=10.0.3), Netdata is pre-installed.
304
+
305
+To use Netdata, the service will need to be enabled and started from the FreeNAS **[CLI](https://github.com/freenas/cli)**.
306
+
307
+To enable the Netdata service:
308
+```
309
+service netdata config set enable=true
310
+```
311
+
312
+To start the netdata service:
313
+```
314
+service netdata start
315
+```
316
+
317
+##### macOS
318
+
319
+Netdata on macOS still has limited charts, but external plugins do work.
320
+
321
+You can either install Netdata with [Homebrew](https://brew.sh/)
322
+
323
+```sh
324
+brew install netdata
325
+```
326
+
327
+or from source:
328
+
329
+```sh
330
+# install Xcode Command Line Tools
331
+xcode-select --install
332
+```
333
+click `Install` in the software update popup window, then
334
+```sh
335
+# install HomeBrew package manager
336
+/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
337
+
338
+# install required packages
339
+brew install ossp-uuid autoconf automake pkg-config
340
+
341
+# download Netdata
342
+git clone https://github.com/netdata/netdata.git --depth=1
343
+
344
+# install Netdata in /usr/local/netdata
345
+cd netdata
346
+sudo ./netdata-installer.sh --install /usr/local
347
+```
348
+
349
+The installer will also install a startup plist to start Netdata when your Mac boots.
350
+
351
+##### Alpine 3.x
352
+
353
+Execute these commands to install Netdata in Alpine Linux 3.x:
354
+
355
+```
356
+# install required packages
357
+apk add alpine-sdk bash curl zlib-dev util-linux-dev libmnl-dev gcc make git autoconf automake pkgconfig python logrotate
358
+
359
+# if you plan to run node.js Netdata plugins
360
+apk add nodejs
361
+
362
+# download Netdata - the directory 'netdata' will be created
363
+git clone https://github.com/netdata/netdata.git --depth=1
364
+cd netdata
365
+
366
+
367
+# build it, install it, start it
368
+./netdata-installer.sh
369
+
370
+
371
+# make Netdata start at boot
372
+echo -e "#!/usr/bin/env bash\n/usr/sbin/netdata" >/etc/local.d/netdata.start
373
+chmod 755 /etc/local.d/netdata.start
374
+
375
+# make Netdata stop at shutdown
376
+echo -e "#!/usr/bin/env bash\nkillall netdata" >/etc/local.d/netdata.stop
377
+chmod 755 /etc/local.d/netdata.stop
378
+
379
+# enable the local service to start automatically
380
+rc-update add local
381
+```
382
+
383
+##### Synology
384
+
385
+The documentation previously recommended installing the Debian Chroot package from the Synology community package sources and then running Netdata from within the chroot. This does not work, as the chroot environment does not have access to `/proc`, and therefore exposes very few metrics to Netdata. Additionally, [this issue](https://github.com/SynoCommunity/spksrc/issues/2758), still open as of 2018/06/24, indicates that the Debian Chroot package is not suitable for DSM versions greater than version 5 and may corrupt system libraries and render the NAS unable to boot.
386
+
387
+The good news is that the 64-bit static installer works fine if your NAS is one that uses the amd64 architecture. It will install the content into `/opt/netdata`, making future removal safe and simple.
388
+
389
+When Netdata is first installed, it will run as _root_. This may or may not be acceptable for you, and since other installations run it as the _netdata_ user, you might wish to do the same. This requires some extra work:
390
+
391
+1. Creat a group `netdata` via the Synology group interface. Give it no access to anything.
392
+2. Create a user `netdata` via the Synology user interface. Give it no access to anything and a random password. Assign the user to the `netdata` group. Netdata will chuid to this user when running.
393
+3. Change ownership of the following directories, as defined in [Netdata Security](../doc/netdata-security.md#security-design):
394
+
395
+```
396
+$ chown -R root:netdata /opt/netdata/usr/share/netdata
397
+$ chown -R netdata:netdata /opt/netdata/var/lib/netdata /opt/netdata/var/cache/netdata
398
+$ chown -R netdata:root /opt/netdata/var/log/netdata
399
+```
400
+
401
+Additionally, as of 2018/06/24, the Netdata installer doesn't recognize DSM as an operating system, so no init script is installed. You'll have to do this manually:
402
+
403
+1. Add [this file](https://gist.github.com/oskapt/055d474d7bfef32c49469c1b53e8225f) as `/etc/rc.netdata`. Make it executable with `chmod 0755 /etc/rc.netdata`.
404
+2. Edit `/etc/rc.local` and add a line calling `/etc/rc.netdata` to have it start on boot:
405
+
406
+```
407
+# Netdata startup
408
+[ -x /etc/rc.netdata ] && /etc/rc.netdata start
409
```