diff options
| author | Joel Hans <joel@netdata.cloud> | 2020-09-29 10:57:52 -0700 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2020-09-29 10:57:52 -0700 |
| commit | 61d7e23eed0503bf591274df70713970213b5c7f (patch) | |
| tree | 125879ff5f780c2937ee206fc510d89e9a91a868 /docs/configure | |
| parent | e3b04fb39a06991d9a2deed0488044dd7d340e3f (diff) | |
Add docsv2 project to master branch (#10000)
* Add overview docs to docsv2 project
* Add quickstart docs to docsv2 project (#9865)
* Init quickstart docs
* Begin work on quickstart guides
* Finish quickstart drafts
* Tweaks to both quickstarts
* Add titles
* Copyedit pass to both docs
* Fixes for Amy and Jen
* Add Get doc to docsv2 project (#9854)
* Init get file
* Add some links
* Change h2 to h1
* Rephrase
* Add configure docs to docsv2 project (#9878)
* Add overview docs to docsv2 project (#9849)
* Init files
* Add drafts of what and why
* Finish initial drafts
* Fix edit URL
* Copyedit pass
* Finish initial drafts of configure docs
* Copyedit all docs
* Fixes for Amy
* Fixes for Jen
* Add collect docs to the docsv2 project (#9932)
* Init files
* Finish first two collect docs
* Finish drafts of collect docs
* Copyedit pass
* Fixes for Amy
* Fix for Jen
* Add visualize docs to the docsv2 project (#9943)
* Add visualize docs
* Copyedits and cleanup
* New images and features
* Copyedit pass and cleanup
* Missing word
* Fixes for Jen
* Add monitor docs to docsv2 project (#9949)
* Finish drafts of monitor docs
* Copyedit pass
* Remove whitespace
* Fixes for Jen
* Add store docs to docsv2 project (#9969)
* Finalize store documents
* Fix import path
* Finishing edit section
* Copyedit pass
* Add export docs to docsv2 project (#9986)
* Add install and claim videos to Get doc
* Finish drafts of exporting docs plus other tweaks
* Init new exporting READMEs
* Copyedit pass and new links
* Fixes for Amy, Vlad, Jen
* Fix links in docsv2 project (#9993)
* Fix links
* Fix a bunch of links ahead of export merge
* Fix additional links
* Fix links, nuke what-is-netdata
* Fixing a few last links
* Improve product images in overview
* Remove extra paren
* Quick tweaks for Jen
* Fixes for Jen
* Access fix
* Remove extra word
Diffstat (limited to 'docs/configure')
| -rw-r--r-- | docs/configure/invite-collaborate.md | 58 | ||||
| -rw-r--r-- | docs/configure/nodes.md | 121 | ||||
| -rw-r--r-- | docs/configure/secure-nodes.md | 121 | ||||
| -rw-r--r-- | docs/configure/spaces-war-rooms.md | 87 |
4 files changed, 387 insertions, 0 deletions
diff --git a/docs/configure/invite-collaborate.md b/docs/configure/invite-collaborate.md new file mode 100644 index 0000000000..0949066c76 --- /dev/null +++ b/docs/configure/invite-collaborate.md @@ -0,0 +1,58 @@ +<!-- +title: "Invite your team and collaborate" +description: "Invite your SRE, DevOPs, or ITOps teams to Netdata Cloud to give everyone insights into your infrastructure from a single pane of glass." +custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/configure/invite-collaborate.md +--> + +# Invite your team and collaborate + +Netdata is designed to make an infrastructure's real-time metrics available and actionable to all organization members. +By inviting others, you can better synchronize with your team or colleagues to understand your infrastructure's +heartbeat. When something goes wrong, you'll be ready to collaboratively troubleshoot complex performance problems from +a single pane of glass. + +## Invite new members + +Invite new users by clicking on your Space's name in the top navigation, and then **Invite more users**, to open the +invitation pane. Admins manage user permissions and have control over who can access specific Spaces and War Rooms. + + + +Enter their email address and name. They can change this name once they accept your invitation. + +Choose which War Rooms you want to add this user to, then click the plus **+** button to add the invitation to the +**New invitations to be sent** queue. Repeat the process with everyone you want to invite to your Space. + +When you're ready to send the new invitations you created, hit the **Send** button. Netdata Cloud sends these +invitations and moves them to the **Invitations awaiting response** category. + +Your team will receive their email invitations momentarily with a prompt to sign in to join your Space. + +## Collaboration with Netdata Cloud + +Netdata Cloud gives teams a single interface to view real-time metrics across their entire infrastructure. Having all +the metrics, alarm statuses, dashboards, and people in one place is a powerful asset for any infrastructure monitoring +team. + +Assets like dashboards and bookmarks are shared between members of a War Room. As soon as one member creates a +dashboard, for example, other members of the same War Room can see it in the War Room's dropdown and supplement it with +additional charts/text. + +Let's say you get an alert from your nodes about an excess of 500-type errors in your Nginx logs. Your team can hop on a +Slack call to begin working together. While one engineer handles creating a new dashboard with a half-dozen relevant +Nginx log metrics, another can dive into the real-time node dashboard and investigate correlated charts in granular +detail. + +## What's next? + +If your team members have trouble signing in, direct them to the [Netdata Cloud sign in +doc](https://learn.netdata.cloud/docs/cloud/manage/sign-in). Or, find answers to other common questions about Netdata +Cloud in our [FAQ](https://learn.netdata.cloud/docs/cloud/faq-glossary). + +Next, we recommend you learn the [basics of node configuration](/docs/configure/nodes.md). While the Netdata Agent is +proudly zero-configuration in most cases, you should understand how to tweak its settings to give you the best Netdata, +for example, to [increase metrics retention](/docs/store/change-metrics-storage.md) and [improve +security](/docs/configure/secure-nodes.md). + +[](<>) diff --git a/docs/configure/nodes.md b/docs/configure/nodes.md new file mode 100644 index 0000000000..5998c1e746 --- /dev/null +++ b/docs/configure/nodes.md @@ -0,0 +1,121 @@ +<!-- +title: "Configure your nodes" +description: "Netdata is zero-configuration for most users, but complex infrastructures may require you to tweak some of the Agent's granular settings." +custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/configure/nodes.md +--> + +# Configure your nodes + +Netdata's zero-configuration collection, storage, and visualization features work for many users, infrastructures, and +use cases, but there are some situations where you might want to configure your nodes. + +For example, you might want to increase metrics retention, configure a collector based on your infrastructure's unique +setup, or secure the local dashboard by restricting it to only connections from `localhost`. + +Whatever the reason, Netdata users should know how to configure individual nodes to act decisively if an incident, +anomaly, or change in infrastructure affects how their Agents should peform. + +## The Netdata config directory + +On most Linux systems, using our [recommended one-line installation](/docs/get/README.md#install-the-netdata-agent), the +**Netdata config directory** is `/etc/netdata/`. The config directory contains several configuration files with the +`.conf` extension, a few directories, and a shell script named `edit-config`. + +> Some operating systems will use `/opt/netdata/etc/netdata/` as the config directory. If you're not sure where yours +> is, navigate to `http://NODE:19999/netdata.conf` in your browser, replacing `NODE` with the IP address or hostname of +> your node, and find the `# config directory = ` setting. The value listed is the config directory for your system. + +All of Netdata's documentation assumes that your config directory is at `/etc/netdata`, and that you're running any +scripts from inside that directory. + +## Netdata's configuration files + +Upon installation, the Netdata config directory contains a few files and directories. + +- `netdata.conf` is the main configuration file. This is where you'll find most configuration options. This doc won't + go into exhaustive detail about each setting. You can read descriptions for each in the [daemon config + doc](/daemon/config/README.md). +- `orig` is a symbolic link to the directory `/usr/lib/netdata/conf.d`, which contains stock configuration files. + Stock versions are copied into the config directory when opened with `edit-config`. _Do not edit the files in + `/usr/lib/netdata/conf.d`, as they are overwritten by updates to the Netdata Agent._ +- `edit-config` is a shell script used for [editing configuration files](#use-edit-config-to-edit-netdataconf). +- `go.d/`, `python.d/`, `charts.d/`, `node.d`/, and `custom-plugins.d/`, which are directories for each of Netdata's + [orchestrators](/collectors/plugins.d/README.md#external-plugins-overview). These directories can each contain + additional `.conf` files for configuring specific collectors. + +## Use `edit-config` to edit `netdata.conf` + +The best way to edit any configuration file is with `edit-config` script. This script opens existing Netdata +configuration files using your system's `$EDITOR`. If the file doesn't yet exist in your config directory, the script +copies the stock version from `/usr/lib/netdata/conf.d` and opens it for editing. + +`edit-config` is the recommended way to easily and safely edit Netdata's configuration. + +Run `edit-config` without any options to see details on its usage and a list of all the configuration files you can +edit. + +```bash +./edit-config +USAGE: + ./edit-config FILENAME + + Copy and edit the stock config file named: FILENAME + if FILENAME is already copied, it will be edited as-is. + + The EDITOR shell variable is used to define the editor to be used. + + Stock config files at: '/usr/lib/netdata/conf.d' + User config files at: '/etc/netdata' + + Available files in '/usr/lib/netdata/conf.d' to copy and edit: + +./apps_groups.conf ./health.d/phpfpm.conf +./aws_kinesis.conf ./health.d/pihole.conf +./charts.d/ap.conf ./health.d/portcheck.conf +./charts.d/apcupsd.conf ./health.d/postgres.conf +... +``` + +To edit `netdata.conf`, run `./edit-config netdata.conf`. You may need to elevate your privileges with `sudo` or another +method for `edit-config` to write into the config directory. Use your `$EDITOR`, make your changes, and save the file. + +> `edit-config` uses the `EDITOR` environment variable on your system to edit the file. On many systems, that is +> defaulted to `vim` or `nano`. To change this variable for the current session (it will revert to the default when you +> reboot), export a new value: `export EDITOR=nano`. Or, [make the change +> permanent](https://stackoverflow.com/questions/13046624/how-to-permanently-export-a-variable-in-linux). + +After you make your changes, you need to restart the Agent with `service netdata restart`. + +Here's an example of editing the node's hostname, which appears in both the local dashboard and in Netdata Cloud. + + + +### Other configuration files + +You can edit any Netdata configuration file using `edit-config`. A few examples: + +```bash +./edit-config apps_groups.conf +./edit-config ebpf.conf +./edit-config health.d/load.conf +./edit-config go.d/prometheus.conf +``` + +The documentation for each of Netdata's components explains which file(s) to edit to achieve the desired behavior. + +## What's next? + +Take advantage of this newfound understanding of node configuration to [add security to your +node](/docs/configure/secure-nodes.md). We have a few best practices based on how you use the Netdata Agent and Netdata +Cloud. + +You can also take what you've learned about node configuration to tweak the Agent's behavior or enable new features: + +- [Enable new collectors](/docs/collect/enable-configure.md) or tweak their behavior. +- [Configure existing health alarms](/docs/monitor/configure-alarms.md) or create new ones. +- [Enable notifications](/docs/monitor/enable-notifications.md) to receive updates about the health of your + infrastructure. +- Change [the long-term metrics retention period](/docs/store/change-metrics-storage.md) using the database engine. + +[](<>) diff --git a/docs/configure/secure-nodes.md b/docs/configure/secure-nodes.md new file mode 100644 index 0000000000..629409f815 --- /dev/null +++ b/docs/configure/secure-nodes.md @@ -0,0 +1,121 @@ +<!-- +title: "Secure your nodes" +description: "Your data and systems are safe with Netdata, but + +we recommend a few easy ways to improve the security of your infrastructure." +custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/configure/secure-nodes.md +--> + +# Secure your nodes + +Upon installation, the Netdata Agent serves the local dashboard at port `19999`. If the node is accessible to the +internet at large, anyone can access the dashboard and your node's metrics at `http://NODE:19999`. We made this decision +so that the local dashboard was immediately accessible to users, and so that we don't dictate how professionals set up +and secure their infrastructures. + +Despite this design decision, your [data](/docs/netdata-security.md#your-data-are-safe-with-netdata) and your +[systems](/docs/netdata-security.md#your-systems-are-safe-with-netdata) are safe with Netdata. Netdata is read-only, +cannot do anything other than present metrics, and runs without special/`sudo` privileges. Also, the local dashboard +only exposes chart metadata and metric values, not raw data. + +While Netdata is secure by design, we believe you should [protect your +nodes](/docs/netdata-security.md#why-netdata-should-be-protected). If left accessible to the internet at large, the +local dashboard could reveal sensitive information about your infrastructure. For example, an attacker can view which +applications you run (databases, webservers, and so on), or see every user account on a node. + +Instead of dictating how to secure your infrastructure, we give you many options to establish security best practices +that align with your goals and your organization's standards. + +- [Disable the local dashboard](#disable-the-local-dashboard): **Simplest and recommended method** for those who have + added nodes to Netdata Cloud and view metrics there. +- [Restrict access to the local dashboard](#restrict-access-to-the-local-dashboard): Allow dashboard access from only + certain IP addresses, such as a trusted static IP or connections from behind a management LAN. Full support for + Netdata Cloud. +- [Use a reverse proxy](#use-a-reverse-proxy): Password-protect a local dashboard and enable TLS to secure it. Full + support for Netdata Cloud. + +## Disable the local dashboard + +This is the _recommended method for those who have claimed their nodes to Netdata Cloud_ and prefer viewing real-time +metrics using the Nodes view and Cloud dashboards. + +You can disable the local dashboard entirely but retain the encrypted Agent-Cloud link ([ACLK](/aclk/README.md)) that +allows you to stream metrics on demand from your nodes via the Netdata Cloud interface. This change mitigates all +concerns about revealing metrics and system design to the internet at large, while keeping all the functionality you +need to view metrics and troubleshoot issues. + +Open `netdata.conf` with `./edit-config netdata.conf`. Scroll down to the `[web]` section, and find the `mode = +static-threaded` setting. To disable the local dashboard, change this setting to `none`. + +```conf +[web] + mode = none +``` + +Save and close the editor, then restart your Agent using `service netdata restart`. If you try to visit the local +dashboard to `http://NODE:19999` again, the connection will fail because that node no longer serves its local dashboard. + +> See the [configuration basics doc](/docs/configure/nodes.md) for details on how to find `netdata.conf` and use +> `edit-config`. + +## Restrict access to the local dashboard + +If you want to keep using the local dashboard, but don't want it exposed to the internet, you can restrict access with +[access lists](/web/server/README.md#access-lists). This method also fully retains the ability to stream metrics +on-demand through Netdata Cloud. + +The `allow connections from` setting helps you allow only certain IP addresses or FQDN/hostnames, such as a trusted +static IP, only `localhost`, or connections from behind a management LAN. + +By default, this setting is `localhost *`. This setting allows connections from `localhost` in addition to _all_ +connections, using the `*` wildcard. You can change this setting using Netdata's [simple +patterns](/libnetdata/simple_pattern/README.md). + +```conf +[web] + # Allow only localhost connections + allow connections from = localhost + + # Allow only from management LAN running on `10.X.X.X` + allow connections from = 10.* + + # Allow connections only from a specific FQDN/hostname + allow connections from = example* +``` + +The `allow connections from` setting is global and restricts access to the dashboard, badges, streaming, API, and +`netdata.conf`, but you can also set each of those access lists more granularly if you choose: + +```conf +[web] + allow connections from = localhost * + allow dashboard from = localhost * + allow badges from = * + allow streaming from = * + allow netdata.conf from = localhost fd* 10.* 192.168.* 172.16.* 172.17.* 172.18.* 172.19.* 172.20.* 172.21.* 172.22.* 172.23.* 172.24.* 172.25.* 172.26.* 172.27.* 172.28.* 172.29.* 172.30.* 172.31.* + allow management from = localhost +``` + +See the [web server](/web/server/README.md#access-lists) docs for additional details about access lists. You can take +access lists one step further by [enabling SSL](/web/server/README.md#enabling-tls-support) to encrypt data in transit. + +## Use a reverse proxy + +You can also put Netdata behind a reverse proxy for additional security while retaining the functionality of both the +local dashboard and Netdata Cloud dashboards. You can use a reverse proxy to password-protect the local dashboard and +enable HTTPS to encrypt metadata and metric values in transit. + +We recommend Nginx, as it's what we use for our [demo server](https://london.my-netdata.io/), and we have a guide +dedicated to [running Netdata behind Nginx](/docs/Running-behind-nginx.md). + +We also have guides for [Apache](/docs/Running-behind-apache.md), [Lighttpd](/docs/Running-behind-lighttpd.md), +[HAProxy](/docs/Running-behind-haproxy.md), and [Caddy](/docs/Running-behind-caddy.md). + +## What's next? + +If you haven't already, be sure to read about [Netdata's security design](/docs/netdata-security.md). + +Next up, learn about [collectors](/docs/collect/how-collectors-work.md) to ensure you're gathering every essential +metric about your node, its applications, and your infrastructure at large. + +[](<>) diff --git a/docs/configure/spaces-war-rooms.md b/docs/configure/spaces-war-rooms.md new file mode 100644 index 0000000000..6b45aab6f0 --- /dev/null +++ b/docs/configure/spaces-war-rooms.md @@ -0,0 +1,87 @@ +<!-- +title: "Set up Spaces and War Rooms" +description: "Netdata Cloud allows people and teams of all sizes to organize their infrastructure and collaborate on anomalies or incidents." +custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/configure/spaces-war-rooms.md +--> + +# Set up Spaces and War Rooms + +Spaces and War Rooms help you organize your real-time infrastructure monitoring experience in Netdata Cloud. You already +created a Space and War Room when you first signed in to Cloud, assuming you weren't invited to an existing Space by +someone else. + +In either case, you can always create new Spaces and War Rooms based on your changing needs or a scaled-up +infrastructure. Let's talk through some strategies for building the most intuitive Cloud experience for your team. + +> This guide assumes you've already [signed in](https://app.netdata.cloud) to Netdata Cloud and finished creating your +> account. If you're not interested in Netdata Cloud's features, you can skip ahead to [node configuration +> basics](/docs/configure/nodes.md). + +## Spaces + +Spaces are high-level containers to help you organize your team members and the nodes they can view in each War Room. +You already have at least one Space in your Netdata Cloud account. + +To create a new Space, click the **+** icon, enter its name, and click **Save**. Netdata Cloud distinguishes between +Spaces with abbreviated versions of their name. Click on any of the icons to switch between them. + + + +The organization you choose will likely be based on two factors: + +1. The fact that any node can be claimed to a single Space. +2. The size of your team and the complexity of the infrastructure you monitor. + +A single Space puts all your metrics in one easily-accessible place, while multiple Spaces creates logical division +between different users and different pieces of a large infrastructure. + +For example, a large organization might have one SRE team for the user-facing SaaS application, and a second IT team for +managing employees' hardware. Since these teams don't monitor the same nodes, they can work in separate Spaces and then +further organize their nodes into War Rooms. + +You can also use multiple Spaces for different aspects of your monitoring "life," such as your work infrastructure +versus your homelab. + +## War Rooms + +War Rooms are granular containers for organizing nodes, viewing key metrics in real-time, and monitoring the health and +alarm status of many nodes. + +War Rooms organize the [at-a-glance Node view](/docs/visualize/view-all-nodes.md) and any [new +dashboards](/docs/visualize/create-dashboards.md) you build. + +We recommend a few strategies for organizing your War Rooms. + +**Service, purpose, location, etc.**: You can group War Rooms by a service (think Nginx, MySQL, Pulsar, and so on), +their purpose (webserver, database, application), their physical location, whether they're baremetal or a Docker +container, the PaaS/cloud provider it runs on, and much more. This allows you to see entire slices of your +infrastructure by moving from one War Room to another. + +**End-to-end apps/services**: If you have a user-facing SaaS product, or an internal service that said product relies +on, you may want to monitor that entire stack in a single War Room. This might include Kubernetes clusters, Docker +containers, proxies, databases, web servers, brokers, and more. End-to-end War Rooms are valuable tools for ensuring the +health and performance of your organization's essential services. + +**Incident response**: You can also create new War Rooms as one of the first steps in your incident response process. +For example, you have a user-facing web app that relies on Apache Pulsar for a message queue, and one of your nodes +using the [Pulsar collector](https://learn.netdata.cloud/docs/agent/collectors/go.d.plugin/modules/pulsar) begins +reporting a suspiciously low messages rate. You can create a War Room called `$year-$month-$day-pulsar-rate`, add all +your Pulsar nodes in addition to nodes they connect to, and begin diagnosing the root cause in a War Room optimized for +getting to resolution as fast as possible. + +For example, here is a War Room based on the node's provider and physical location (**us-east-1**). + + + +## What's next? + +Once you've figured out an organizational structure that works for your infrastructure, it's time to [invite your +team](/docs/configure/invite-collaborate.md). You can invite any number of colleagues to help you collectively +troubleshoot the most complex of infrastructure-wide performance issues. + +If you don't have a team or aren't ready to invite them, you can skip ahead to learn the [basics of node +configuration](/docs/configure/nodes.md). + +[](<>) |