Merge pull request #5322 from heyitsanthony/port-docs

scrub legacy ports and update tls information
This commit is contained in:
Anthony Romano 2016-05-11 16:32:45 -07:00
commit be0c38ec2b
19 changed files with 50 additions and 59 deletions

View File

@ -1,2 +1,2 @@
FROM golang:onbuild
EXPOSE 4001 7001 2379 2380
EXPOSE 2379 2380

View File

@ -256,17 +256,17 @@ DNS [SRV records][rfc-srv] can be used as a discovery mechanism.
The `-discovery-srv` flag can be used to set the DNS domain name where the discovery SRV records can be found.
The following DNS SRV records are looked up in the listed order:
* _etcd-server-ssl._tcp.example.com
* _etcd-server-tls._tcp.example.com
* _etcd-server._tcp.example.com
If `_etcd-server-ssl._tcp.example.com` is found then etcd will attempt the bootstrapping process over SSL.
If `_etcd-server-tls._tcp.example.com` is found then etcd will attempt the bootstrapping process over TLS.
To help clients discover the etcd cluster, the following DNS SRV records are looked up in the listed order:
* _etcd-client._tcp.example.com
* _etcd-client-ssl._tcp.example.com
* _etcd-client-tls._tcp.example.com
If `_etcd-client-ssl._tcp.example.com` is found, clients will attempt to communicate with the etcd cluster over SSL.
If `_etcd-client-tls._tcp.example.com` is found, clients will attempt to communicate with the etcd cluster over TLS.
#### Create DNS SRV records

View File

@ -2,9 +2,9 @@
etcd is configurable through command-line flags and environment variables. Options set on the command line take precedence over those from the environment.
The format of environment variable for flag `--my-flag` is `ETCD_MY_FLAG`. It applies to all flags.
The format of environment variable for flag `--my-flag` is `ETCD_MY_FLAG`. It applies to all flags.
The [official etcd ports][iana-ports] are 2379 for client requests, and 2380 for peer communication. Some legacy code and documentation still references ports 4001 and 7001, but all new etcd use and discussion should adopt the assigned ports.
The [official etcd ports][iana-ports] are 2379 for client requests and 2380 for peer communication. The etcd ports can be set to accept TLS traffic, non-TLS traffic, or both TLS and non-TLS traffic.
To start etcd automatically using custom settings at startup in Linux, using a [systemd][systemd-intro] unit is highly recommended.
@ -16,7 +16,7 @@ To start etcd automatically using custom settings at startup in Linux, using a [
+ Human-readable name for this member.
+ default: "default"
+ env variable: ETCD_NAME
+ This value is referenced as this node's own entries listed in the `--initial-cluster` flag (Ex: `default=http://localhost:2380` or `default=http://localhost:2380,default=http://localhost:7001`). This needs to match the key used in the flag if you're using [static bootstrapping][build-cluster]. When using discovery, each member must have a unique name. `Hostname` or `machine-id` can be a good choice.
+ This value is referenced as this node's own entries listed in the `--initial-cluster` flag (e.g., `default=http://localhost:2380`). This needs to match the key used in the flag if you're using [static bootstrapping][build-cluster]. When using discovery, each member must have a unique name. `Hostname` or `machine-id` can be a good choice.
### --data-dir
+ Path to the data directory.
@ -45,14 +45,14 @@ To start etcd automatically using custom settings at startup in Linux, using a [
### --listen-peer-urls
+ List of URLs to listen on for peer traffic. This flag tells the etcd to accept incoming requests from its peers on the specified scheme://IP:port combinations. Scheme can be either http or https.If 0.0.0.0 is specified as the IP, etcd listens to the given port on all interfaces. If an IP address is given as well as a port, etcd will listen on the given port and interface. Multiple URLs may be used to specify a number of addresses and ports to listen on. The etcd will respond to requests from any of the listed addresses and ports.
+ default: "http://localhost:2380,http://localhost:7001"
+ default: "http://localhost:2380"
+ env variable: ETCD_LISTEN_PEER_URLS
+ example: "http://10.0.0.1:2380"
+ invalid example: "http://example.com:2380" (domain name is invalid for binding)
### --listen-client-urls
+ List of URLs to listen on for client traffic. This flag tells the etcd to accept incoming requests from the clients on the specified scheme://IP:port combinations. Scheme can be either http or https. If 0.0.0.0 is specified as the IP, etcd listens to the given port on all interfaces. If an IP address is given as well as a port, etcd will listen on the given port and interface. Multiple URLs may be used to specify a number of addresses and ports to listen on. The etcd will respond to requests from any of the listed addresses and ports.
+ default: "http://localhost:2379,http://localhost:4001"
+ default: "http://localhost:2379"
+ env variable: ETCD_LISTEN_CLIENT_URLS
+ example: "http://10.0.0.1:2379"
+ invalid example: "http://example.com:2379" (domain name is invalid for binding)
@ -83,13 +83,13 @@ To start etcd automatically using custom settings at startup in Linux, using a [
### --initial-advertise-peer-urls
+ List of this member's peer URLs to advertise to the rest of the cluster. These addresses are used for communicating etcd data around the cluster. At least one must be routable to all cluster members. These URLs can contain domain names.
+ default: "http://localhost:2380,http://localhost:7001"
+ default: "http://localhost:2380"
+ env variable: ETCD_INITIAL_ADVERTISE_PEER_URLS
+ example: "http://example.com:2380, http://10.0.0.1:2380"
### --initial-cluster
+ Initial cluster configuration for bootstrapping.
+ default: "default=http://localhost:2380,default=http://localhost:7001"
+ default: "default=http://localhost:2380"
+ env variable: ETCD_INITIAL_CLUSTER
+ The key is the value of the `--name` flag for each node provided. The default uses `default` for the key because this is the default for the `--name` flag.
@ -107,7 +107,7 @@ To start etcd automatically using custom settings at startup in Linux, using a [
### --advertise-client-urls
+ List of this member's client URLs to advertise to the rest of the cluster. These URLs can contain domain names.
+ default: "http://localhost:2379,http://localhost:4001"
+ default: "http://localhost:2379"
+ env variable: ETCD_ADVERTISE_CLIENT_URLS
+ example: "http://example.com:2379, http://10.0.0.1:2379"
+ Be careful if you are advertising URLs such as http://localhost:2379 from a cluster member and are using the proxy feature of etcd. This will cause loops, because the proxy will be forwarding requests to itself until its resources (memory, file descriptors) are eventually depleted.

View File

@ -1,6 +1,6 @@
# Security Model
etcd supports SSL/TLS as well as authentication through client certificates, both for clients to server as well as peer (server to server / cluster) communication.
etcd supports automatic TLS as well as authentication through client certificates for both clients to server as well as peer (server to server / cluster) communication.
To get up and running you first need to have a CA certificate and a signed key pair for one member. It is recommended to create and sign a new key pair for every member in a cluster.
@ -52,7 +52,7 @@ This should start up fine and you can now test the configuration by speaking HTT
$ curl --cacert /path/to/ca.crt https://127.0.0.1:2379/v2/keys/foo -XPUT -d value=bar -v
```
You should be able to see the handshake succeed. Because we use self-signed certificates with our own certificate authorities you need to provide the CA to curl using the `--cacert` option. Another possibility would be to add your CA certificate to the trusted certificates on your system (usually in `/etc/ssl/certs`).
You should be able to see the handshake succeed. Because we use self-signed certificates with our own certificate authorities you need to provide the CA to curl using the `--cacert` option. Another possibility would be to add your CA certificate to the trusted certificates on your system (usually in `/etc/pki/tls/certs` or `/etc/ssl/certs`).
**OSX 10.9+ Users**: curl 7.30.0 on OSX 10.9+ doesn't understand certificates passed in on the command line.
Instead you must import the dummy ca.crt directly into the keychain or add the `-k` flag to curl to ignore errors.
@ -153,14 +153,7 @@ When client authentication is enabled for an etcd member, the administrator must
## Frequently Asked Questions
### My cluster is not working with peer tls configuration?
The internal protocol of etcd v2.0.x uses a lot of short-lived HTTP connections.
So, when enabling TLS you may need to increase the heartbeat interval and election timeouts to reduce internal cluster connection churn.
A reasonable place to start are these values: ` --heartbeat-interval 500 --election-timeout 2500`.
These issues are resolved in the etcd v2.1.x series of releases which uses fewer connections.
### I'm seeing a SSLv3 alert handshake failure when using SSL client authentication?
### I'm seeing a SSLv3 alert handshake failure when using TLS client authentication?
The `crypto/tls` package of `golang` checks the key usage of the certificate public key before using it.
To use the certificate public key to do client auth, we need to add `clientAuth` to `Extended Key Usage` when creating the certificate public key.

View File

@ -14,7 +14,7 @@
etcd is a distributed, consistent key-value store for shared configuration and service discovery, with a focus on being:
* *Simple*: well-defined, user-facing API (gRPC)
* *Secure*: optional SSL client cert authentication
* *Secure*: automatic TLS with optional client cert authentication
* *Fast*: benchmarked 1000s of writes/s per instance
* *Reliable*: properly distributed using Raft

View File

@ -23,10 +23,10 @@ election-timeout: 1000
quota-backend-bytes: 0
# List of comma separated URLs to listen on for peer traffic.
listen-peer-urls: http://localhost:2380,http://localhost:7001
listen-peer-urls: http://localhost:2380
# List of comma separated URLs to listen on for client traffic.
listen-client-urls: http://localhost:2379,http://localhost:4001
listen-client-urls: http://localhost:2379
# Maximum number of snapshot files to retain (0 is unlimited).
max-snapshots: 5
@ -39,11 +39,11 @@ cors:
# List of this member's peer URLs to advertise to the rest of the cluster.
# The URLs needed to be a comma-separated list.
initial-advertise-peer-urls: http://localhost:2380,http://localhost:7001
initial-advertise-peer-urls: http://localhost:2380
# List of this member's client URLs to advertise to the public.
# The URLs needed to be a comma-separated list.
advertise-client-urls: http://localhost:2379,http://localhost:4001
advertise-client-urls: http://localhost:2379
# Discovery URL used to bootstrap the cluster.
discovery:

View File

@ -30,12 +30,12 @@ You can also build etcdctl from source using the build script found in the paren
### --peers
+ a comma-delimited list of machine addresses in the cluster
+ default: `"http://127.0.0.1:4001,http://127.0.0.1:2379"`
+ default: `"http://127.0.0.1:2379"`
+ env variable: ETCDCTL_PEERS
### --endpoint
+ a comma-delimited list of machine addresses in the cluster
+ default: `"http://127.0.0.1:4001,http://127.0.0.1:2379"`
+ default: `"http://127.0.0.1:2379"`
+ env variable: ETCDCTL_ENDPOINT
+ Without `--no-sync` flag, this will be overwritten by etcd cluster when it does internal sync.

View File

@ -41,7 +41,7 @@ import (
const (
defaultName = "default"
defaultInitialAdvertisePeerURLs = "http://localhost:2380,http://localhost:7001"
defaultInitialAdvertisePeerURLs = "http://localhost:2380"
)
var (
@ -191,7 +191,7 @@ func initialClusterFromName(name string) string {
if name == "" {
n = defaultName
}
return fmt.Sprintf("%s=http://localhost:2380,%s=http://localhost:7001", n, n)
return fmt.Sprintf("%s=http://localhost:2380", n, n)
}
// makeWAL creates a WAL for the initial cluster

View File

@ -46,10 +46,10 @@ const (
clusterStateFlagExisting = "existing"
defaultName = "default"
defaultInitialAdvertisePeerURLs = "http://localhost:2380,http://localhost:7001"
defaultAdvertiseClientURLs = "http://localhost:2379,http://localhost:4001"
defaultListenPeerURLs = "http://localhost:2380,http://localhost:7001"
defaultListenClientURLs = "http://localhost:2379,http://localhost:4001"
defaultInitialAdvertisePeerURLs = "http://localhost:2380"
defaultAdvertiseClientURLs = "http://localhost:2379"
defaultListenPeerURLs = "http://localhost:2380"
defaultListenClientURLs = "http://localhost:2379"
// maxElectionMs specifies the maximum value of election timeout.
// More details are listed in ../Documentation/tuning.md#time-parameters.
@ -471,7 +471,7 @@ func initialClusterFromName(name string) string {
if name == "" {
n = defaultName
}
return fmt.Sprintf("%s=http://localhost:2380,%s=http://localhost:7001", n, n)
return fmt.Sprintf("%s=http://localhost:2380", n)
}
func (cfg config) isNewCluster() bool { return cfg.clusterState.String() == clusterStateFlagNew }

View File

@ -44,9 +44,9 @@ member flags:
time (in milliseconds) of a heartbeat interval.
--election-timeout '1000'
time (in milliseconds) for an election to timeout. See tuning documentation for details.
--listen-peer-urls 'http://localhost:2380,http://localhost:7001'
--listen-peer-urls 'http://localhost:2380'
list of URLs to listen on for peer traffic.
--listen-client-urls 'http://localhost:2379,http://localhost:4001'
--listen-client-urls 'http://localhost:2379'
list of URLs to listen on for client traffic.
--max-snapshots '` + strconv.Itoa(defaultMaxSnapshots) + `'
maximum number of snapshot files to retain (0 is unlimited).
@ -59,16 +59,16 @@ member flags:
clustering flags:
--initial-advertise-peer-urls 'http://localhost:2380,http://localhost:7001'
--initial-advertise-peer-urls 'http://localhost:2380'
list of this member's peer URLs to advertise to the rest of the cluster.
--initial-cluster 'default=http://localhost:2380,default=http://localhost:7001'
--initial-cluster 'default=http://localhost:2380'
initial cluster configuration for bootstrapping.
--initial-cluster-state 'new'
initial cluster state ('new' or 'existing').
--initial-cluster-token 'etcd-cluster'
initial cluster token for the etcd cluster during bootstrap.
Specifying this can protect you from unintended cross-cluster interaction when running multiple clusters.
--advertise-client-urls 'http://localhost:2379,http://localhost:4001'
--advertise-client-urls 'http://localhost:2379'
list of this member's client URLs to advertise to the public.
The client URLs advertised should be accessible to machines that talk to etcd cluster. etcd client libraries parse these URLs to connect to the cluster.
--discovery ''

View File

@ -484,7 +484,7 @@ func createConfigChangeEnts(ids []uint64, self uint64, term, index uint64) []raf
if !found {
m := membership.Member{
ID: types.ID(self),
RaftAttributes: membership.RaftAttributes{PeerURLs: []string{"http://localhost:7001", "http://localhost:2380"}},
RaftAttributes: membership.RaftAttributes{PeerURLs: []string{"http://localhost:2380"}},
}
ctx, err := json.Marshal(m)
if err != nil {

View File

@ -74,7 +74,7 @@ func TestGetIDs(t *testing.T) {
func TestCreateConfigChangeEnts(t *testing.T) {
m := membership.Member{
ID: types.ID(1),
RaftAttributes: membership.RaftAttributes{PeerURLs: []string{"http://localhost:7001", "http://localhost:2380"}},
RaftAttributes: membership.RaftAttributes{PeerURLs: []string{"http://localhost:2380"}},
}
ctx, err := json.Marshal(m)
if err != nil {

View File

@ -1,8 +1,8 @@
#!/bin/bash -e
leader=http://10.240.201.15:4001
leader=http://10.240.201.15:2379
# assume three servers
servers=( http://10.240.201.15:4001 http://10.240.212.209:4001 http://10.240.95.3:4001 )
servers=( http://10.240.201.15:2379 http://10.240.212.209:2379 http://10.240.95.3:2379 )
keyarray=( 64 256 )

View File

@ -1,6 +1,6 @@
# Use goreman to run `go get github.com/mattn/goreman`
# One of the four etcd members falls back to a proxy
etcd1: ../../bin/etcd --name infra1 --listen-client-urls http://127.0.0.1:4001 --advertise-client-urls http://127.0.0.1:4001 --listen-peer-urls http://127.0.0.1:7001 --initial-advertise-peer-urls http://127.0.0.1:7001
etcd2: ../../bin/etcd --name infra2 --listen-client-urls http://127.0.0.1:4002 --advertise-client-urls http://127.0.0.1:4002 --listen-peer-urls http://127.0.0.1:7002 --initial-advertise-peer-urls http://127.0.0.1:7002
etcd3: ../../bin/etcd --name infra3 --listen-client-urls http://127.0.0.1:4003 --advertise-client-urls http://127.0.0.1:4003 --listen-peer-urls http://127.0.0.1:7003 --initial-advertise-peer-urls http://127.0.0.1:7003
etcd4: ../../bin/etcd --name infra4 --listen-client-urls http://127.0.0.1:4004 --advertise-client-urls http://127.0.0.1:4004 --listen-peer-urls http://127.0.0.1:7004 --initial-advertise-peer-urls http://127.0.0.1:7004
etcd1: ../../bin/etcd --name infra1 --listen-client-urls http://127.0.0.1:2379 --advertise-client-urls http://127.0.0.1:2379 --listen-peer-urls http://127.0.0.1:2380 --initial-advertise-peer-urls http://127.0.0.1:2380
etcd2: ../../bin/etcd --name infra2 --listen-client-urls http://127.0.0.1:12379 --advertise-client-urls http://127.0.0.1:12379 --listen-peer-urls http://127.0.0.1:12380 --initial-advertise-peer-urls http://127.0.0.1:12380
etcd3: ../../bin/etcd --name infra3 --listen-client-urls http://127.0.0.1:22379 --advertise-client-urls http://127.0.0.1:22379 --listen-peer-urls http://127.0.0.1:22380 --initial-advertise-peer-urls http://127.0.0.1:22380
etcd4: ../../bin/etcd --name infra4 --listen-client-urls http://127.0.0.1:32379 --advertise-client-urls http://127.0.0.1:32379 --listen-peer-urls http://127.0.0.1:32380 --initial-advertise-peer-urls http://127.0.0.1:32380

View File

@ -1,9 +1,9 @@
# Use goreman to run `go get github.com/mattn/goreman`
etcd1: ../../bin/etcd --name infra1 --listen-client-urls https://localhost:4001 --advertise-client-urls https://localhost:4001 --listen-peer-urls https://localhost:7001 --initial-advertise-peer-urls https://localhost:7001 --initial-cluster-token etcd-cluster-1 --initial-cluster 'infra1=https://localhost:7001,infra2=https://localhost:7002,infra3=https://localhost:7003' --initial-cluster-state new --cert-file=certs/etcd1.pem --key-file=certs/etcd1-key.pem --peer-cert-file=certs/etcd1.pem --peer-key-file=certs/etcd1-key.pem --peer-client-cert-auth --peer-trusted-ca-file=certs/ca.pem
etcd1: ../../bin/etcd --name infra1 --listen-client-urls https://localhost:2379 --advertise-client-urls https://localhost:2379 --listen-peer-urls https://localhost:2380 --initial-advertise-peer-urls https://localhost:2380 --initial-cluster-token etcd-cluster-1 --initial-cluster 'infra1=https://localhost:2380,infra2=https://localhost:12380,infra3=https://localhost:22380' --initial-cluster-state new --cert-file=certs/etcd1.pem --key-file=certs/etcd1-key.pem --peer-cert-file=certs/etcd1.pem --peer-key-file=certs/etcd1-key.pem --peer-client-cert-auth --peer-trusted-ca-file=certs/ca.pem
etcd2: ../../bin/etcd --name infra2 --listen-client-urls https://localhost:4002 --advertise-client-urls https://localhost:4002 --listen-peer-urls https://localhost:7002 --initial-advertise-peer-urls https://localhost:7002 --initial-cluster-token etcd-cluster-1 --initial-cluster 'infra1=https://localhost:7001,infra2=https://localhost:7002,infra3=https://localhost:7003' --initial-cluster-state new --cert-file=certs/etcd2.pem --key-file=certs/etcd2-key.pem --peer-cert-file=certs/etcd2.pem --peer-key-file=certs/etcd2-key.pem --peer-client-cert-auth --peer-trusted-ca-file=certs/ca.pem
etcd2: ../../bin/etcd --name infra2 --listen-client-urls https://localhost:12379 --advertise-client-urls https://localhost:12379 --listen-peer-urls https://localhost:12380 --initial-advertise-peer-urls https://localhost:12380 --initial-cluster-token etcd-cluster-1 --initial-cluster 'infra1=https://localhost:2380,infra2=https://localhost:12380,infra3=https://localhost:22380' --initial-cluster-state new --cert-file=certs/etcd2.pem --key-file=certs/etcd2-key.pem --peer-cert-file=certs/etcd2.pem --peer-key-file=certs/etcd2-key.pem --peer-client-cert-auth --peer-trusted-ca-file=certs/ca.pem
etcd3: ../../bin/etcd --name infra3 --listen-client-urls https://localhost:4003 --advertise-client-urls https://localhost:4003 --listen-peer-urls https://localhost:7003 --initial-advertise-peer-urls https://localhost:7003 --initial-cluster-token etcd-cluster-1 --initial-cluster 'infra1=https://localhost:7001,infra2=https://localhost:7002,infra3=https://localhost:7003' --initial-cluster-state new --cert-file=certs/etcd3.pem --key-file=certs/etcd3-key.pem --peer-cert-file=certs/etcd3.pem --peer-key-file=certs/etcd3-key.pem --peer-client-cert-auth --peer-trusted-ca-file=certs/ca.pem
etcd3: ../../bin/etcd --name infra3 --listen-client-urls https://localhost:22379 --advertise-client-urls https://localhost:22379 --listen-peer-urls https://localhost:22380 --initial-advertise-peer-urls https://localhost:22380 --initial-cluster-token etcd-cluster-1 --initial-cluster 'infra1=https://localhost:2380,infra2=https://localhost:12380,infra3=https://localhost:22380' --initial-cluster-state new --cert-file=certs/etcd3.pem --key-file=certs/etcd3-key.pem --peer-cert-file=certs/etcd3.pem --peer-key-file=certs/etcd3-key.pem --peer-client-cert-auth --peer-trusted-ca-file=certs/ca.pem
proxy: ../../bin/etcd --name proxy1 --proxy=on --listen-client-urls https://localhost:8080 --initial-cluster 'infra1=https://localhost:7001,infra2=https://localhost:7002,infra3=https://localhost:7003' --cert-file=certs/proxy1.pem --key-file=certs/proxy1-key.pem --trusted-ca-file=certs/ca.pem --peer-cert-file=certs/proxy1.pem --peer-key-file=certs/proxy1-key.pem --peer-client-cert-auth --peer-trusted-ca-file=certs/ca.pem
proxy: ../../bin/etcd --name proxy1 --proxy=on --listen-client-urls https://localhost:8080 --initial-cluster 'infra1=https://localhost:2380,infra2=https://localhost:12380,infra3=https://localhost:22380' --cert-file=certs/proxy1.pem --key-file=certs/proxy1-key.pem --trusted-ca-file=certs/ca.pem --peer-cert-file=certs/proxy1.pem --peer-key-file=certs/proxy1-key.pem --peer-client-cert-auth --peer-trusted-ca-file=certs/ca.pem

View File

@ -56,8 +56,6 @@ acbuild --debug set-exec -- /etcd
acbuild --debug mount add data-dir /data-dir
acbuild --debug port add legacy-client tcp 4001
acbuild --debug port add legacy-peer tcp 7001
acbuild --debug port add client tcp 2379
acbuild --debug port add peer tcp 2380

View File

@ -12,7 +12,7 @@ cat <<DF > ${IMAGEDIR}/Dockerfile
FROM scratch
ADD etcd /
ADD etcdctl /
EXPOSE 4001 7001 2379 2380
EXPOSE 2379 2380
ENTRYPOINT ["/etcd"]
DF

View File

@ -5,7 +5,7 @@ usage:
```
-iface="eth0": interface for sniffing traffic on
-period=1: seconds between submissions
-ports="2379,4001": etcd listening ports
-ports="2379": etcd listening ports
-promiscuous=true: whether to perform promiscuous sniffing or not.
-topk=10: submit stats for the top <K> sniffed paths
```

View File

@ -146,7 +146,7 @@ func streamRouter(ports []uint16, parsedPackets chan *pcap.Packet, processors []
// 4. open the pcap handler
// 5. hand off packets from the handler to the decoder
func main() {
portsArg := flag.String("ports", "2379,4001", "etcd listening ports")
portsArg := flag.String("ports", "2379", "etcd listening ports")
iface := flag.String("iface", "eth0", "interface for sniffing traffic on")
promisc := flag.Bool("promiscuous", true, "promiscuous mode")
period := flag.Uint("period", 1, "seconds between submissions")