lukevmorris
GitHub
commit
7f1247f18a
|
|
@ -127,7 +127,7 @@ The Chronograf team has identified and is working on the following issues:
|
|||
|
||||
## Installation
|
||||
|
||||
Check out the [INSTALLATION](https://github.com/influxdata/chronograf/blob/master/docs/INSTALLATION.md) guide to get up and running with Chronograf with as little configuration and code as possible.
|
||||
Check out the [INSTALLATION](https://docs.influxdata.com/chronograf/v1.3/introduction/installation/) guide to get up and running with Chronograf with as little configuration and code as possible.
|
||||
|
||||
We recommend installing Chronograf using one of the [pre-built packages](https://influxdata.com/downloads/#chronograf). Then start Chronograf using:
|
||||
|
||||
|
|
@ -161,8 +161,8 @@ docker pull quay.io/influxdb/chronograf:latest
|
|||
|
||||
## Documentation
|
||||
|
||||
[INSTALLATION](https://github.com/influxdata/chronograf/blob/master/docs/INSTALLATION.md) will get you up and running with Chronograf with as little configuration and code as possible.
|
||||
See the [GETTING STARTED](https://github.com/influxdata/chronograf/blob/master/docs/GETTING_STARTED.md) guide to get familiar with Chronograf's main features.
|
||||
[INSTALLATION](https://docs.influxdata.com/chronograf/v1.3/introduction/installation/) will get you up and running with Chronograf with as little configuration and code as possible.
|
||||
See the [GETTING STARTED](https://docs.influxdata.com/chronograf/v1.3/introduction/getting-started/) guide to get familiar with Chronograf's main features.
|
||||
|
||||
Documentation for Telegraf, InfluxDB, and Kapacitor are available at https://docs.influxdata.com/.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,126 +1 @@
|
|||
# Getting Started with Chronograf
|
||||
|
||||
Let's get familiar with some of Chronograf's main features.
|
||||
In the next sections, we'll show you how Chronograf makes the monitoring and alerting for your infrastructure easy to configure and maintain.
|
||||
|
||||
If you haven't installed Chronograf check out the [Installation Guide](https://github.com/influxdata/chronograf/blob/master/docs/INSTALLATION.md).
|
||||
|
||||
## Host List
|
||||
|
||||
The `HOST LIST` page is essentially Chronograf's home page.
|
||||
It lists every host that is sending [Telegraf](https://github.com/influxdata/telegraf) data to your [InfluxDB](https://github.com/influxdata/influxdb) instance as well a some information about each host's CPU usage, load, and configured apps.
|
||||
|
||||
|
||||
|
||||
The Chronograf instance shown above is connected to two hosts (`telegraf-narnia` and `telegraf-neverland`).
|
||||
The first host is using 0.35% of its total CPU and has a load of 0.00.
|
||||
It has one configured app: `system`.
|
||||
Apps are Telegraf [input plugins](https://github.com/influxdata/telegraf#input-plugins) that have dashboard templates in Chronograf.
|
||||
|
||||
Click on the app on the `HOST LIST` page to access its dashboard template.
|
||||
The dashboard offers [pre-created](https://github.com/influxdata/chronograf/tree/master/canned) graphs of the input's data that are currently in InfluxDB.
|
||||
Here's the dashboard template for Telegraf's [system stats](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/system) input plugin:
|
||||
|
||||
|
||||
|
||||
Hover over the graphs to get additional information about the data.
|
||||
In addition, select alternative refresh intervals, alternative time ranges, and enter presentation mode with the icons in the top right corner.
|
||||
|
||||
See the [README](https://github.com/influxdata/chronograf#dashboard-templates) for a complete list of the apps supported by Chronograf.
|
||||
|
||||
## Data Explorer
|
||||
|
||||
Chronograf's Data Explorer gives you the tools to dig in and create personalized visualizations of your data.
|
||||
|
||||
### Generate Visualizations with the Query Builder
|
||||
|
||||
Use the query builder to easily generate [InfluxQL](https://docs.influxdata.com/influxdb/latest/query_language/) queries and create beautiful visualizations:
|
||||
|
||||
|
||||
|
||||
### Generate Visualizations with the Raw Query Editor
|
||||
|
||||
Paste an existing [InfluxQL](https://docs.influxdata.com/influxdb/latest/query_language/) query or write a query from scratch with the `InfluxQL` editor:
|
||||
|
||||
|
||||
|
||||
### Other Features
|
||||
Select an alternative refresh interval (1), an alternative time range (2), and view query results in tabular format (3):
|
||||
|
||||
|
||||
|
||||
## Create and View Alerts
|
||||
|
||||
Chronograf also offers a UI for generating [Kapacitor](https://github.com/influxdata/kapacitor) alerting rules and viewing those alerts as they occur.
|
||||
|
||||
### Create an Alert Rule
|
||||
Easily create a Kapacitor alert rule on the `KAPACITOR RULES` page.
|
||||
Access the `KAPACITOR RULES` page by hovering over the third item in the left navigation menu and selecting `Kapacitor Rules`.
|
||||
Then, click on the `Create New Rule` button to create a new alert rule.
|
||||
|
||||
The example rule shown below operates on data from Telegraf's [system stats](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/system) input plugin and sends a simple threshold alert to Slack:
|
||||
|
||||
|
||||
|
||||
The `Select a Time Series` section includes an [InfluxQL](https://docs.influxdata.com/influxdb/latest/query_language/) query builder which allows you to specify the target data for the alert rule.
|
||||
The example shown above is working with the system stat's `usage_idle` [field](https://docs.influxdata.com/influxdb/v1.1/concepts/glossary/#field) in the `cpu` [measurement](https://docs.influxdata.com/influxdb/v1.1/concepts/glossary/#measurement).
|
||||
|
||||
The `Values` section defines the alert rule.
|
||||
It supports three rule types:
|
||||
|
||||
* Threshold Rule - alert if the data cross a boundary
|
||||
* Relative Rule - alert if the data change relative to the data in a different time range
|
||||
* Deadman Rule - alert if no data are received for the specified time range
|
||||
|
||||
The example above creates a simple threshold rule that sends an alert when `usage_idle` values are less than 96%.
|
||||
Notice that the graph provides a preview of the target data and the configured rule boundary.
|
||||
|
||||
Lastly, the `Alert Message` section allows you to personalize the alert message and select an alert endpoint.
|
||||
The rule shown above sends alert messages to a Slack channel.
|
||||
Here's an example of the alert messages in Slack:
|
||||
|
||||
|
||||
|
||||
Currently, Chronograf supports the following alert endpoints: HipChat, OpsGenie, PagerDuty, Sensu, Slack, SMTP, Talk, Telegram, and VictorOps.
|
||||
You can configure your alert endpoints on the `CONFIGURE KAPACITOR` page.
|
||||
|
||||
### View all Active Alerts
|
||||
|
||||
See all active alerts on the `ALERTING` page, and filter them by `Name`,
|
||||
`Level`, and `Host`:
|
||||
|
||||
|
||||
|
||||
### Alerta TICKscript Parser
|
||||
|
||||
Chronograf offers a parser for TICKscripts that use the [Alerta](https://docs.influxdata.com/kapacitor/latest/nodes/alert_node/#alerta) output.
|
||||
This is a new feature in version 1.2.0-beta2.
|
||||
|
||||
To use the TICKscript parser:
|
||||
|
||||
* Select Alerta as the output when creating or editing an alert rule
|
||||
* Paste your existing TICKscript in the text input (spacing doesn't matter!)
|
||||
* Save your rule
|
||||
|
||||
You're good to go! The system automatically parses your TICKscript and creates a
|
||||
Chronograf-friendly alert rule.
|
||||
|
||||
> **Notes:**
|
||||
>
|
||||
* Currently, the Alerta TICKscript parser requires users to **paste** their existing TICKscript in the text input. The parser does not support manually entering or editing a TICKscript.
|
||||
* The parser requires users to whitespace delimit any services listed in the TICKscript's [`.services()` attribute](https://docs.influxdata.com/kapacitor/latest/nodes/alert_node/#alerta-services).
|
||||
|
||||
## Manage Users and Queries
|
||||
|
||||
The `ADMIN` section of Chronograf supports managing InfluxDB users and queries.
|
||||
|
||||
### User Management
|
||||
|
||||
Create, assign permissions to, and delete [InfluxDB users](https://docs.influxdata.com/influxdb/latest/query_language/authentication_and_authorization/#user-types-and-privileges).
|
||||
In version 1.2.0-beta5, Chronograf only supports assigning `ALL` permissions to users; that is, read and write permissions to every database in the InfluxDB instance.
|
||||
|
||||
### Query Management
|
||||
|
||||
View currently-running queries and stop expensive queries from running on the InfluxDB instance:
|
||||
|
||||
|
||||
**We've moved our documentation!** Check out the latest [getting started guide](https://docs.influxdata.com/chronograf/v1.3/introduction/getting-started/) on InfluxData's [main docs site](https://docs.influxdata.com/chronograf/v1.3/).
|
||||
|
|
@ -1,251 +1 @@
|
|||
# Installation Guide
|
||||
|
||||
Chronograf is the user interface component of InfluxData's TICK stack.
|
||||
It makes owning the monitoring and alerting for your infrastructure easy to setup and maintain.
|
||||
|
||||
The next sections will get you up and running with Chronograf with as little configuration and
|
||||
code as possible.
|
||||
By the end of this document you will have downloaded, installed, and configured all four packages of the
|
||||
TICK stack ([Telegraf](https://github.com/influxdata/telegraf), [InfluxDB](https://github.com/influxdata/influxdb), Chronograf, and [Kapacitor](https://github.com/influxdata/kapacitor)), and you will be all set to monitor your infrastructure.
|
||||
|
||||
## Operating System Support
|
||||
Chronograf and the other components of the TICK stack are supported on a large number of operating systems and hardware architectures.
|
||||
This guide will walk you through getting set up on an Ubuntu 16.04 installation,
|
||||
and it will be applicable to most flavors of Linux.
|
||||
Check out the [downloads](https://www.influxdata.com/downloads/) page for links to the binaries of your choice.
|
||||
|
||||
## InfluxDB Setup
|
||||
|
||||
[InfluxDB](https://docs.influxdata.com/influxdb/latest/) is the time series database that serves as the data storage component of the TICK stack.
|
||||
|
||||
#### 1. Download and Install InfluxDB
|
||||
```
|
||||
wget https://dl.influxdata.com/influxdb/releases/influxdb_1.2.2_amd64.deb
|
||||
sudo dpkg -i influxdb_1.2.2_amd64.deb
|
||||
```
|
||||
|
||||
#### 2. Start InfluxDB
|
||||
There's no need to edit InfluxDB's default [configuration](https://docs.influxdata.com/influxdb/latest/administration/config/) for the purposes of this guide.
|
||||
Just start InfluxDB with:
|
||||
```
|
||||
sudo systemctl start influxdb
|
||||
```
|
||||
|
||||
#### 3. Verify that InfluxDB is Running
|
||||
Run the `SHOW DATABASES` command using curl:
|
||||
```
|
||||
curl "http://localhost:8086/query?q=show+databases"
|
||||
```
|
||||
If InfluxDB is up and running, you should see an object that contains the `_internal` database:
|
||||
```json
|
||||
{"results":[{"statement_id":0,"series":[{"name":"databases","columns":["name"],"values":[["_internal"]]}]}]}
|
||||
```
|
||||
So far so good! You're ready to move on to the next section. Note that there's no need to create your own database on your InfluxDB instance; the other components of the TICK stack will handle that for you.
|
||||
|
||||
## Kapacitor Setup
|
||||
|
||||
[Kapacitor](https://docs.influxdata.com/kapacitor/latest/) is the data processing platform of the TICK stack.
|
||||
Kapacitor is responsible for creating and sending alerts in Chronograf.
|
||||
|
||||
#### 1. Download and Install Kapacitor
|
||||
```
|
||||
wget https://dl.influxdata.com/kapacitor/releases/kapacitor_1.2.0_amd64.deb
|
||||
sudo dpkg -i kapacitor_1.2.0_amd64.deb
|
||||
```
|
||||
|
||||
#### 2. Start Kapacitor
|
||||
```
|
||||
sudo systemctl start kapacitor
|
||||
```
|
||||
|
||||
#### 3. Verify that Kapacitor is Running
|
||||
Check the `task` list of Kapacitor with:
|
||||
```
|
||||
kapacitor list tasks
|
||||
```
|
||||
If Kapacitor is up and running, you should see an empty list of tasks:
|
||||
```
|
||||
ID Type Status Executing Databases and Retention Policies
|
||||
```
|
||||
|
||||
If there was a problem you will see an error message:
|
||||
```
|
||||
Get http://localhost:9092/kapacitor/v1/tasks?dot-view=attributes&fields=type&fields=status&fields=executing&fields=dbrps&limit=100&offset=0&pattern=&replay-id=&script-format=formatted: dial tcp [::1]:9092: getsockopt: connection refused
|
||||
```
|
||||
|
||||
## Telegraf Setup
|
||||
|
||||
[Telegraf](https://docs.influxdata.com/telegraf/latest/) is the metrics gathering agent in the TICK stack.
|
||||
For the purposes of this guide, we will setup Telegraf on the same machine as InfluxDB.
|
||||
We will also configure Telegraf's basic [system stats](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/system) input plugin to send metrics to that InfluxDB instance.
|
||||
|
||||
In a production environment, Telegraf would be installed on your servers and would point the output to an InfluxDB instance on a separate machine.
|
||||
Ultimately, you will configure a Telegraf input plugin for each application that you want to monitor.
|
||||
|
||||
> Note:
|
||||
Currently, Chronograf requires users to run Telegraf's [system stats](https://github.com/influxdata/telegraf/blob/master/plugins/inputs/system/SYSTEM_README.md) plugin to ensure that all content appears on the [HOST LIST](https://github.com/influxdata/chronograf/blob/master/docs/GETTING_STARTED.md#host-list) page.
|
||||
This is a known issue.
|
||||
|
||||
#### 1. Download and Install Telegraf
|
||||
```
|
||||
wget https://dl.influxdata.com/telegraf/releases/telegraf_1.2.1_amd64.deb
|
||||
sudo dpkg -i telegraf_1.2.1_amd64.deb
|
||||
```
|
||||
|
||||
#### 2. Start Telegraf
|
||||
```
|
||||
sudo systemctl start telegraf
|
||||
```
|
||||
|
||||
#### 3. Verify Telegraf's Configuration and that the Process is Running
|
||||
Step 2 should create a configuration file with [system stats](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/system) as an input plugin and InfluxDB as an output plugin.
|
||||
|
||||
Double check the configuration file at `/etc/telegraf/telegraf.conf` for the relevant input and output settings.
|
||||
The `OUTPUT PLUGINS` section should have the following settings for the InfluxDB output:
|
||||
```
|
||||
[[outputs.influxdb]]
|
||||
## The full HTTP or UDP endpoint URL for your InfluxDB instance.
|
||||
## Multiple urls can be specified as part of the same cluster,
|
||||
## this means that only ONE of the urls will be written to each interval.
|
||||
# urls = ["udp://localhost:8089"] # UDP endpoint example
|
||||
urls = ["http://localhost:8086"] # required
|
||||
## The target database for metrics (telegraf will create it if not exists).
|
||||
database = "telegraf" # required
|
||||
|
||||
## Retention policy to write to. Empty string writes to the default rp.
|
||||
retention_policy = ""
|
||||
## Write consistency (clusters only), can be: "any", "one", "quorum", "all"
|
||||
write_consistency = "any"
|
||||
|
||||
## Write timeout (for the InfluxDB client), formatted as a string.
|
||||
## If not provided, will default to 5s. 0s means no timeout (not recommended).
|
||||
timeout = "5s"
|
||||
# username = "telegraf"
|
||||
# password = "metricsmetricsmetricsmetrics"
|
||||
## Set the user agent for HTTP POSTs (can be useful for log differentiation)
|
||||
# user_agent = "telegraf"
|
||||
## Set UDP payload size, defaults to InfluxDB UDP Client default (512 bytes)
|
||||
# udp_payload = 512
|
||||
```
|
||||
Next, the `INTPUT PLUGINS` section should have the following settings for the system stats input:
|
||||
```
|
||||
# Read metrics about cpu usage
|
||||
[[inputs.cpu]]
|
||||
## Whether to report per-cpu stats or not
|
||||
percpu = true
|
||||
## Whether to report total system cpu stats or not
|
||||
totalcpu = true
|
||||
## If true, collect raw CPU time metrics.
|
||||
collect_cpu_time = false
|
||||
|
||||
|
||||
# Read metrics about disk usage by mount point
|
||||
[[inputs.disk]]
|
||||
## By default, telegraf gather stats for all mountpoints.
|
||||
## Setting mountpoints will restrict the stats to the specified mountpoints.
|
||||
# mount_points = ["/"]
|
||||
|
||||
## Ignore some mountpoints by filesystem type. For example (dev)tmpfs (usually
|
||||
## present on /run, /var/run, /dev/shm or /dev).
|
||||
ignore_fs = ["tmpfs", "devtmpfs"]
|
||||
|
||||
|
||||
# Read metrics about disk IO by device
|
||||
[[inputs.diskio]]
|
||||
## By default, telegraf will gather stats for all devices including
|
||||
## disk partitions.
|
||||
## Setting devices will restrict the stats to the specified devices.
|
||||
# devices = ["sda", "sdb"]
|
||||
## Uncomment the following line if you need disk serial numbers.
|
||||
# skip_serial_number = false
|
||||
|
||||
|
||||
# Get kernel statistics from /proc/stat
|
||||
[[inputs.kernel]]
|
||||
# no configuration
|
||||
|
||||
|
||||
# Read metrics about memory usage
|
||||
[[inputs.mem]]
|
||||
# no configuration
|
||||
|
||||
|
||||
# Get the number of processes and group them by status
|
||||
[[inputs.processes]]
|
||||
# no configuration
|
||||
|
||||
|
||||
# Read metrics about swap memory usage
|
||||
[[inputs.swap]]
|
||||
# no configuration
|
||||
|
||||
|
||||
# Read metrics about system load & uptime
|
||||
[[inputs.system]]
|
||||
# no configuration
|
||||
```
|
||||
If this looks like your configuration then we can run a quick test to ensure that the system stats are being written to InfluxDB:
|
||||
```
|
||||
curl "http://localhost:8086/query?q=select+*+from+telegraf..cpu"
|
||||
```
|
||||
If Telegraf is setup properly you should see a lot of JSON data; if the output is empty than something has gone wrong.
|
||||
|
||||
## Chronograf Setup
|
||||
Now that we are collecting data with Telegraf and storing data with InfluxDB, it's time to install Chronograf to begin viewing and monitoring the data.
|
||||
|
||||
#### 1. Download and Install Chronograf
|
||||
```
|
||||
wget https://dl.influxdata.com/chronograf/releases/chronograf_1.2.0~beta10_amd64.deb
|
||||
sudo dpkg -i chronograf_1.2.0~beta10_amd64.deb
|
||||
```
|
||||
|
||||
#### 2. Start Chronograf
|
||||
```
|
||||
sudo systemctl start chronograf
|
||||
```
|
||||
|
||||
#### 3. Connect to Chronograf
|
||||
Assuming everything is up and running we should be able to connect to and configure Chronograf.
|
||||
Point your web browser to `http://localhost:8888` (replace `localhost` with your server's IP if you're not running on `localhost`).
|
||||
|
||||
You should see a welcome page:
|
||||
|
||||
|
||||
|
||||
The next steps connect Chronograf to your InfluxDB instance.
|
||||
For the `Connection String`, enter the hostname or IP of the machine that InfluxDB is running on, and be sure to include InfluxDB's default port: `8086`.
|
||||
Next, name the connection string; this can be anything you want.
|
||||
There's no need to edit the last three inputs; [authorization is disabled](https://docs.influxdata.com/influxdb/latest/administration/config/#auth-enabled-false) in InfluxDB's default configuration so `Username` and `Password` can remain blank, and Telegraf's [default database name](https://github.com/influxdata/telegraf/blob/master/etc/telegraf.conf#L89) is `telegraf`.
|
||||
|
||||
Click `Connect New Source` to move on to the `HOST LIST` page:
|
||||
|
||||
|
||||
|
||||
You should see your machine's hostname on the page along with information about its CPU usage and load.
|
||||
Assuming you've configured Telegraf's system stats input plugin, `system` should appear in the `Apps` column.
|
||||
Go ahead and click on the hostname to see a series of system level graphs about
|
||||
your host:
|
||||
|
||||
|
||||
|
||||
#### 4. Connect Chronograf to Kapacitor
|
||||
|
||||
The final step in the installation process is to connect Chronograf to Kapacitor.
|
||||
Hover over the last item in the left navigation menu and click `Kapacitor` to
|
||||
get to the `CONFIGURE KAPACITOR` page.
|
||||
|
||||
|
||||
|
||||
For the `Connection String`, enter the hostname or IP of the machine that Kapacitor is running on, and be sure to include Kapacitor's default port: `9092`.
|
||||
Next, name the connection string; this can be anything you want.
|
||||
There's no need to enter any information for the `Username` and `Password` inputs as [authorization is disabled](https://docs.influxdata.com/influxdb/latest/administration/config/#auth-enabled-false) in InfluxDB's default configuration.
|
||||
Finally, click `Connect Kapacitor`.
|
||||
|
||||
If Kapacitor successfully connects you'll see an
|
||||
Configure [Alert Endpoints](https://docs.influxdata.com/kapacitor/v1.0/nodes/alert_node/)
|
||||
section below the `Connection Details` section:
|
||||
|
||||
|
||||
|
||||
That's it! You've successfully downloaded, installed, and configured each component of the TICK stack.
|
||||
Check out the [Getting Started](https://github.com/influxdata/chronograf/blob/master/docs/GETTING_STARTED.md) guide to familiarize yourself with Chronograf and see all that it can do for you!
|
||||
**We've moved our documentation!** Check out the latest [installation guide](https://docs.influxdata.com/chronograf/v1.3/introduction/installation/) on InfluxData's [main docs site](https://docs.influxdata.com/chronograf/v1.3/).
|
||||
181
docs/auth.md
181
docs/auth.md
|
|
@ -1,180 +1 @@
|
|||
## Chronograf with OAuth 2.0 (Github-style)
|
||||
|
||||
OAuth 2.0 Style Authentication
|
||||
|
||||
### TL;DR
|
||||
#### Github
|
||||
|
||||
```sh
|
||||
export AUTH_DURATION=1h # force login every hour
|
||||
export TOKEN_SECRET=supersupersecret # Signing secret
|
||||
export GH_CLIENT_ID=b339dd4fddd95abec9aa # Github client id
|
||||
export GH_CLIENT_SECRET=260041897d3252c146ece6b46ba39bc1e54416dc # Github client secret
|
||||
export GH_ORGS=biffs-gang # Restrict to GH orgs
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
To use authentication in Chronograf, both the OAuth provider and JWT signature
|
||||
need to be configured.
|
||||
|
||||
**Note:** If you're using the `--basepath` option when starting Chronograf, you will need to add the same basepath to the callback URL of any OAuth provider that you configure.
|
||||
|
||||
#### Configuring JWT signature
|
||||
|
||||
Set a [JWT](https://tools.ietf.org/html/rfc7519) signature to a random string. This is needed for all OAuth2 providers that you choose to configure. *Keep this random string around!*
|
||||
|
||||
You'll need it each time you start a chronograf server because it is used to verify user authorization. If you are running multiple chronograf servers in an HA configuration set the `TOKEN_SECRET` on each to allow users to stay logged in. If you want to log all users out every time the server restarts, change the value of `TOKEN_SECRET` to a different value on each restart.
|
||||
|
||||
```sh
|
||||
export TOKEN_SECRET=supersupersecret
|
||||
```
|
||||
|
||||
### Github
|
||||
#### Creating Github OAuth Application
|
||||
|
||||
To create a Github OAuth Application follow the [Register your app](https://developer.github.com/guides/basics-of-authentication/#registering-your-app) instructions.
|
||||
Essentially, you'll register your application [here](https://github.com/settings/applications/new)
|
||||
|
||||
The `Homepage URL` should be Chronograf's full server name and port. If you are running it locally for example, make it `http://localhost:8888`
|
||||
|
||||
The `Authorization callback URL` must be the location of the `Homepage URL` plus `/oauth/github/callback`. For example, if `Homepage URL` was
|
||||
`http://localhost:8888` then the `Authorization callback URL` should be `http://localhost:8888/oauth/github/callback`.
|
||||
|
||||
Github will provide a `Client ID` and `Client Secret`. To register these values with chronograf set the following environment variables:
|
||||
|
||||
* `GH_CLIENT_ID`
|
||||
* `GH_CLIENT_SECRET`
|
||||
|
||||
For example:
|
||||
|
||||
```sh
|
||||
export GH_CLIENT_ID=b339dd4fddd95abec9aa
|
||||
export GH_CLIENT_SECRET=260041897d3252c146ece6b46ba39bc1e54416dc
|
||||
```
|
||||
|
||||
#### Optional Github Organizations
|
||||
|
||||
To require an organization membership for a user, set the `GH_ORGS` environment variables
|
||||
```sh
|
||||
export GH_ORGS=biffs-gang
|
||||
```
|
||||
|
||||
If the user is not a member, then the user will not be allowed access.
|
||||
|
||||
To support multiple organizations use a comma delimted list like so:
|
||||
|
||||
```sh
|
||||
export GH_ORGS=hill-valley-preservation-sociey,the-pinheads
|
||||
```
|
||||
|
||||
### Google
|
||||
|
||||
#### Creating Google OAuth Application
|
||||
|
||||
You will need to obtain a client ID and an application secret by following the steps under "Basic Steps" [here](https://developers.google.com/identity/protocols/OAuth2). Chronograf will also need to be publicly accessible via a fully qualified domain name so that Google properly redirects users back to the application.
|
||||
|
||||
This information should be set in the following ENVs:
|
||||
|
||||
* `GOOGLE_CLIENT_ID`
|
||||
* `GOOGLE_CLIENT_SECRET`
|
||||
* `PUBLIC_URL`
|
||||
|
||||
Alternatively, this can also be set using the command line switches:
|
||||
|
||||
* `--google-client-id`
|
||||
* `--google-client-secret`
|
||||
* `--public-url`
|
||||
|
||||
#### Optional Google Domains
|
||||
|
||||
Similar to Github's organization restriction, Google authentication can be restricted to permit access to Chronograf from only specific domains. These are configured using the `GOOGLE_DOMAINS` ENV or the `--google-domains` switch. Multiple domains are separated with a comma. For example, if we wanted to permit access only from biffspleasurepalace.com and savetheclocktower.com the ENV would be set as follows:
|
||||
|
||||
```sh
|
||||
export GOOGLE_DOMAINS=biffspleasurepalance.com,savetheclocktower.com
|
||||
```
|
||||
|
||||
### Heroku
|
||||
|
||||
#### Creating Heroku Application
|
||||
|
||||
To obtain a client ID and application secret for Heroku, you will need to follow the guide posted [here](https://devcenter.heroku.com/articles/oauth#register-client). Once your application has been created, those two values should be inserted into the following ENVs:
|
||||
|
||||
* `HEROKU_CLIENT_ID`
|
||||
* `HEROKU_SECRET`
|
||||
|
||||
The equivalent command line switches are:
|
||||
|
||||
* `--heroku-client-id`
|
||||
* `--heroku-secret`
|
||||
|
||||
#### Optional Heroku Organizations
|
||||
|
||||
Like the other OAuth2 providers, access to Chronograf via Heroku can be restricted to members of specific Heroku organizations. This is controlled using the `HEROKU_ORGS` ENV or the `--heroku-organizations` switch and is comma-separated. If we wanted to permit access from the `hill-valley-preservation-society` orgization and `the-pinheads` organization, we would use the following ENV:
|
||||
|
||||
```sh
|
||||
export HEROKU_ORGS=hill-valley-preservation-sociey,the-pinheads
|
||||
```
|
||||
|
||||
### Generic OAuth2 Provider
|
||||
#### Creating OAuth Application using your own provider
|
||||
|
||||
The generic OAuth2 provider is very similiar to the Github provider, but,
|
||||
you are able to set your own authentication, token and API URLs.
|
||||
|
||||
The callback URL path will be `/oauth/generic/callback`. So, if your chronograf
|
||||
is hosted at `https://localhost:8888` then the full callback URL would be
|
||||
`https://localhost:8888/oauth/generic/callback`
|
||||
|
||||
The generic OAuth2 provider has many settings that are required.
|
||||
|
||||
* `GENERIC_CLIENT_ID` : this application's client [identifier](https://tools.ietf.org/html/rfc6749#section-2.2) issued by the provider
|
||||
* `GENERIC_CLIENT_SECRET` : this application's [secret](https://tools.ietf.org/html/rfc6749#section-2.3.1) issued by the provider
|
||||
* `GENERIC_AUTH_URL` : OAuth 2.0 provider's authorization [endpoint](https://tools.ietf.org/html/rfc6749#section-3.1) URL
|
||||
* `GENERIC_TOKEN_URL` : OAuth 2.0 provider's token endpoint [endpoint](https://tools.ietf.org/html/rfc6749#section-3.2) is used by the client to obtain an access token
|
||||
* `TOKEN_SECRET` : Used to validate OAuth [state](https://tools.ietf.org/html/rfc6749#section-4.1.1) response. (see above)
|
||||
|
||||
#### Optional Scopes
|
||||
By default chronograf will ask for the `user:email`
|
||||
[scope](https://tools.ietf.org/html/rfc6749#section-3.3)
|
||||
of the client. If your
|
||||
provider scopes email access under a different scope or scopes provide them as
|
||||
comma separated values in the `GENERIC_SCOPES` environment variable.
|
||||
|
||||
```sh
|
||||
export GENERIC_SCOPES="openid,email" # Requests access to openid and email scopes
|
||||
```
|
||||
|
||||
#### Optional Email domains
|
||||
Also, the generic OAuth2 provider has a few optional parameters as well.
|
||||
|
||||
* `GENERIC_API_URL` : URL that returns [OpenID UserInfo JWT](https://connect2id.com/products/server/docs/api/userinfo) (specifically email address)
|
||||
* `GENERIC_DOMAINS` : Email domains user's email address must use.
|
||||
|
||||
#### Configuring the look of the login page
|
||||
|
||||
To configure the copy of the login page button text, set `GENERIC_NAME`.
|
||||
|
||||
For example with
|
||||
|
||||
```sh
|
||||
export GENERIC_NAME="Hill Valley Preservation Society"
|
||||
```
|
||||
|
||||
the button text will be `Login with Hill Valley Preservation Society`.
|
||||
|
||||
### Optional: Configuring Authentication Duration
|
||||
|
||||
By default, auth will remain valid for 30 days via a cookie stored in the browser. This duration can be changed with the environment variable `AUTH_DURATION`. For example, to change it to 1 hour, use:
|
||||
|
||||
```sh
|
||||
export AUTH_DURATION=1h
|
||||
```
|
||||
|
||||
The duration uses the golang [time duration format](https://golang.org/pkg/time/#ParseDuration), so the largest time unit is `h` (hours). So to change it to 45 days, use:
|
||||
|
||||
```sh
|
||||
export AUTH_DURATION=1080h
|
||||
```
|
||||
|
||||
Additionally, for greater security, if you want to require re-authentication every time the browser is closed, set `AUTH_DURATION` to `0`. This will make the cookie transient (aka "in-memory").
|
||||
**We've moved our documentation!** Check out the latest [authentication content](https://docs.influxdata.com/chronograf/v1.3/administration/security-best-practices/#chronograf-with-oauth-2-0-authentication) on InfluxData's [main docs site](https://docs.influxdata.com/chronograf/v1.3/).
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 42 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 39 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 537 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 73 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 72 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 111 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 1.0 MiB |
Binary file not shown.
|
Before Width: | Height: | Size: 108 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 137 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 35 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 35 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 30 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 580 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 9.7 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 20 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 556 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 98 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 432 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 81 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 36 KiB |
70
docs/tls.md
70
docs/tls.md
|
|
@ -1,69 +1 @@
|
|||
## Chronograf TLS
|
||||
|
||||
Chronograf supports TLS to securely communicate between the browser and server via
|
||||
HTTPS.
|
||||
|
||||
We recommend using HTTPS with Chronograf. If you are not using a TLS termination proxy,
|
||||
you can run Chronograf's server with TLS connections.
|
||||
### TL;DR
|
||||
|
||||
```sh
|
||||
chronograf --cert=my.crt --key=my.key
|
||||
```
|
||||
|
||||
### Running Chronograf with TLS
|
||||
|
||||
Chronograf server has command line and environment variable options to specify
|
||||
the certificate and key files. The server reads and parses a public/private key
|
||||
pair from these files. The files must contain PEM encoded data.
|
||||
|
||||
In Chronograf all command line options also have a corresponding environment
|
||||
variable.
|
||||
|
||||
To specify the certificate file either use the `--cert` CLI option or `TLS_CERTIFICATE`
|
||||
environment variable.
|
||||
|
||||
To specify the key file either use the `--key` CLI option or `TLS_PRIVATE_KEY`
|
||||
environment variable.
|
||||
|
||||
To specify the certificate and key if both are in the same file either use the `--cert`
|
||||
CLI option or `TLS_CERTIFICATE` environment variable.
|
||||
|
||||
#### Example with CLI options
|
||||
```sh
|
||||
chronograf --cert=my.crt --key=my.key
|
||||
```
|
||||
|
||||
#### Example with environment variables
|
||||
```sh
|
||||
TLS_CERTIFICATE=my.crt TLS_PRIVATE_KEY=my.key chronograf
|
||||
```
|
||||
|
||||
#### Docker example with environment variables
|
||||
```sh
|
||||
docker run -v /host/path/to/certs:/certs -e TLS_CERTIFICATE=/certs/my.crt -e TLS_PRIVATE_KEY=/certs/my.key quay.io/influxdb/chronograf:latest
|
||||
```
|
||||
|
||||
### Testing with self-signed certificates
|
||||
In a production environment you should not use self-signed certificates. However,
|
||||
for testing it is fast to create your own certs.
|
||||
|
||||
To create a cert and key in one file with openssl:
|
||||
|
||||
```sh
|
||||
openssl req -x509 -newkey rsa:4096 -sha256 -nodes -keyout testing.pem -out testing.pem -subj "/CN=localhost" -days 365
|
||||
```
|
||||
|
||||
Next, set the environment variable `TLS_CERTIFICATE`:
|
||||
```sh
|
||||
export TLS_CERTIFICATE=$PWD/testing.pem
|
||||
```
|
||||
|
||||
Run chronograf:
|
||||
|
||||
```sh
|
||||
./chronograf
|
||||
INFO[0000] Serving chronograf at https://[::]:8888 component=server
|
||||
```
|
||||
|
||||
In the first log message you should see `https` rather than `http`.
|
||||
**We've moved our documentation!** Check out the latest [TLS content](https://docs.influxdata.com/chronograf/v1.3/administration/security-best-practices/#tls) on InfluxData's [main docs site](https://docs.influxdata.com/chronograf/v1.3/).
|
||||
|
|
|
|||
|
|
@ -1,121 +1 @@
|
|||
# Use Cases
|
||||
|
||||
Chronograf works with the other components of the TICK stack to provide a user interface for monitoring and alerting on your infrastructure.
|
||||
This document describes common setup use cases for Chronograf.
|
||||
|
||||
## Use Case 1: Setup for Monitoring Several Servers
|
||||
|
||||
Suppose you want to use Chronograf to monitor several servers.
|
||||
This section describes a simple setup for monitoring CPU, disk, and memory usage on three servers.
|
||||
|
||||
### Architecture Overview
|
||||
|
||||
|
||||
|
||||
Each of the three servers has its own [Telegraf](https://github.com/influxdata/telegraf) instance.
|
||||
Those instances are configured to collect CPU, disk, and memory data using Telegraf's [system stats](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/system) input plugin.
|
||||
Each Telegraf instance is also configured to send those data to a single [InfluxDB](https://github.com/influxdata/influxdb) instance.
|
||||
When Telegraf sends data to InfluxDB, it automatically [tags](https://docs.influxdata.com/influxdb/latest/concepts/glossary/#tag) those data with the relevant server's hostname.
|
||||
|
||||
The single InfluxDB instance is connected to Chronograf.
|
||||
Chronograf uses the `host` tag in the Telegraf data to populate the [HOST LIST](https://github.com/influxdata/chronograf/blob/master/docs/GETTING_STARTED.md#host-list) page and provide other hostname-specific information in the user interface.
|
||||
|
||||
### Setup Description
|
||||
|
||||
To start out, we [install and start](https://github.com/influxdata/chronograf/blob/master/docs/INSTALLATION.md#influxdb-setup) InfluxDB on a separate server.
|
||||
We recommend installing InfluxDB on its own [machine](https://docs.influxdata.com/influxdb/latest/guides/hardware_sizing/) for performance purposes.
|
||||
InfluxDB's default [configuration](https://docs.influxdata.com/influxdb/latest/administration/config/) doesn't require any adjustments for this particular use case.
|
||||
|
||||
Next, we [install](https://www.influxdata.com/downloads/) Telegraf on each server that we want to monitor.
|
||||
Before starting the three Telegraf services we need to make some edits to Telegraf's [configuration file](https://github.com/influxdata/telegraf/blob/master/docs/CONFIGURATION.md) (`/etc/telegraf/telegraf.conf`).
|
||||
First, we configure each instance to use the system stats plugin to collect CPU, disk, and memory data.
|
||||
The system stats plugin is actually enabled by default so there's no additional work to do here.
|
||||
We just double check that `[[inputs.cpu]]`, `[[inputs.disk]]`, and `[[inputs.mem]]` are uncommented in the `INPUT PLUGINS` section of Telegraf's configuration file:
|
||||
|
||||
```
|
||||
###############################################################################
|
||||
# INPUT PLUGINS #
|
||||
###############################################################################
|
||||
|
||||
# Read metrics about cpu usage
|
||||
[[inputs.cpu]] #✅
|
||||
## Whether to report per-cpu stats or not
|
||||
percpu = true
|
||||
## Whether to report total system cpu stats or not
|
||||
totalcpu = true
|
||||
## If true, collect raw CPU time metrics.
|
||||
collect_cpu_time = false
|
||||
|
||||
|
||||
# Read metrics about disk usage by mount point
|
||||
[[inputs.disk]] #✅
|
||||
## By default, telegraf gather stats for all mountpoints.
|
||||
## Setting mountpoints will restrict the stats to the specified mountpoints.
|
||||
# mount_points = ["/"]
|
||||
|
||||
## Ignore some mountpoints by filesystem type. For example (dev)tmpfs (usually
|
||||
## present on /run, /var/run, /dev/shm or /dev).
|
||||
ignore_fs = ["tmpfs", "devtmpfs"]
|
||||
|
||||
[...]
|
||||
|
||||
# Read metrics about memory usage
|
||||
[[inputs.mem]] #✅
|
||||
# no configuration
|
||||
```
|
||||
|
||||
Our next edit to Telegraf's configuration file ensures that each Telegraf instance sends data to our single InfluxDB instance.
|
||||
To do this, we edit the `urls` setting in the `OUTPUT PLUGINS` section to point to the IP of our InfluxDB instance:
|
||||
|
||||
```
|
||||
###############################################################################
|
||||
# OUTPUT PLUGINS #
|
||||
###############################################################################
|
||||
|
||||
# Configuration for influxdb server to send metrics to
|
||||
[[outputs.influxdb]]
|
||||
## The full HTTP or UDP endpoint URL for your InfluxDB instance.
|
||||
## Multiple urls can be specified as part of the same cluster,
|
||||
## this means that only ONE of the urls will be written to each interval.
|
||||
# urls = ["udp://localhost:8089"] # UDP endpoint example
|
||||
urls = ["http://<InfluxDB-IP>:8086"] # 💥 Edit here!💥
|
||||
## The target database for metrics (telegraf will create it if not exists).
|
||||
database = "telegraf" # required
|
||||
```
|
||||
Now that we've configured our inputs and outputs, we [start](https://github.com/influxdata/chronograf/blob/master/docs/INSTALLATION.md#2-start-telegraf) the Telegraf service on all three servers.
|
||||
Telegraf begins by creating a database in InfluxDB called `telegraf` (that name is configurable), and Telegraf starts writing system stats data to that database.
|
||||
Note that Telegraf automatically creates a `host` [tag](https://docs.influxdata.com/influxdb/latest/concepts/glossary/#tag) that records the hostname of the server that sent the data.
|
||||
Here's a sample of some CPU usage data in InfluxDB:
|
||||
|
||||
```
|
||||
name: cpu
|
||||
time usage_idle host <--- Telegraf's auto-generated tag
|
||||
---- ---------- ----
|
||||
2016-11-29T22:41:00Z 99.70000000000253 server-01
|
||||
2016-11-29T22:41:00Z 99.79959919839698 server-02
|
||||
2016-11-29T22:41:00Z 98.1037924151472 server-03
|
||||
2016-11-29T22:41:10Z 99.60000000000036 server-01
|
||||
2016-11-29T22:41:10Z 99.49698189131892 server-02
|
||||
2016-11-29T22:41:10Z 99.6996996996977 server-03
|
||||
2016-11-29T22:41:20Z 98.89889889889365 server-01
|
||||
2016-11-29T22:41:20Z 99.40119760479097 server-02
|
||||
2016-11-29T22:41:20Z 99.60039960039995 server-03
|
||||
```
|
||||
|
||||
Finally, we [install and start](https://github.com/influxdata/chronograf/blob/master/docs/INSTALLATION.md#chronograf-setup) Chronograf.
|
||||
Once we [connect](https://github.com/influxdata/chronograf/blob/master/docs/INSTALLATION.md#3-connect-to-chronograf) Chronograf to our InfluxDB
|
||||
instance, Chronograf uses Telegraf's `host` tag to populate the [HOST LIST](https://github.com/influxdata/chronograf/blob/master/docs/GETTING_STARTED.md#host-list) page:
|
||||
|
||||
|
||||
|
||||
The system stats dashboard template shows the CPU, Disk, and Memory metrics for the selected hostname:
|
||||
|
||||
|
||||
|
||||
Finally, you can create queries in the [Data Explorer](https://github.com/influxdata/chronograf/blob/master/docs/GETTING_STARTED.md#data-explorer) that graph results per hostname:
|
||||
|
||||
|
||||
|
||||
## Use Case 2: Setup the TICK Stack in a Kubernetes Instance
|
||||
|
||||
Check out our 20-minute [webinar](https://vimeo.com/193632831) for how to spin up the TICK Stack in a Kubernetes instance.
|
||||
**We've moved our documentation!** Check our latest [guides](https://docs.influxdata.com/chronograf/v1.3/guides/) on InfluxData's [main docs site](https://docs.influxdata.com/chronograf/v1.3/).
|
||||
|
|
|
|||
Loading…
Reference in New Issue