Skip to content

Commit f412581

Browse files
HofiOneHofiOne
authored
Failover doc fixes (syslog-ng#274)
Enahnced version of syslog-ng#271
2 parents 8c982b2 + 27f512a commit f412581

4 files changed

Lines changed: 91 additions & 156 deletions

File tree

‎_includes/doc/admin-guide/options/failback-modes.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
When {{ site.product.short_name }} starts up, it always connects to the primary server first. In the failover() option there is a possibility to customize the failover modes.
2+
3+
Depending on how you set the failback() option, {{ site.product.short_name }} behaves as follows:
4+
5+
- **round-robin mode**: If failback() is not set, {{ site.product.short_name }} does not attempt to return to the primary server even if it becomes available. In case the failover server fails, {{ site.product.short_name }} attempts to connect the next failover server in the list in round-robin fashion.
6+
7+
Example: round-robin mode
8+
9+
In the following example {{ site.product.short_name }} handles the logservers in round-robin fashion if the primary logserver becomes inaccessible (therefore failback() option is not set).
10+
11+
```config
12+
destination d_network {
13+
network(
14+
"primary-server.com"
15+
port(601)
16+
failover( servers("failover-server1", "failover-server2") )
17+
);
18+
};
19+
```
20+
21+
- **failback mode**: If failback() is set, {{ site.product.short_name }} attempts to return to the primary server.
22+
23+
**WARNING:** The failback() option works properly only for TCP-based connections; do not use it with the connectionless UDP protocol.
24+
{: .notice--warning}
25+
26+
After {{ site.product.short_name }} connects a secondary server during a failover, it sends a probe every tcp-probe-interval() seconds towards the primary server. If the primary logserver responds with a TCP ACK packet, the probe is successful. When the number of successful probes reaches the value set in the successful-probes-required() option, {{ site.product.short_name }} tries to connect the primary server using the last probe.
27+
28+
**NOTE:** {{ site.product.short_name }} always waits for the result of the last probe before sending the next message. So if one connection attempt takes longer than the configured interval, that is, it waits for connection time out, you may experience longer intervals between actual probes.
29+
{: .notice--info}
30+
31+
Example: failback mode
32+
33+
In the following example {{ site.product.short_name }} attempts to return to the primary logserver, as set in the failback() option: it will check if the server is accessible every tcp-probe-interval() seconds, and reconnect to the primary logserver after three successful connection attempts.
34+
35+
```config
36+
destination d_network_2 {
37+
network(
38+
"primary-server.com"
39+
port(601)
40+
failover(
41+
servers("failover-server1", "failover-server2")
42+
failback(
43+
successful-probes-required(5)
44+
tcp-probe-interval(10)
45+
)
46+
)
47+
);
48+
};
49+
```

‎_includes/doc/admin-guide/options/failover.md‎

Lines changed: 30 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -4,93 +4,37 @@
44
3.17 and later. For details about how client-side failover works, see
55
Client-side failover.
66

7-
### servers()
8-
9-
| Type: | list of IP addresses and fully-qualified domain names|
10-
| Default: | empty |
11-
12-
*Description:* Specifies a secondary destination server where log messages are sent if the primary server becomes inaccessible. To list several failover servers, separate the address of the servers with comma. By default, {{ site.product.short_name }} waits for the a server before switching to the next failover server is set in the time-reopen() option.
13-
If failback() is not set, {{ site.product.short_name }} does not attempt to return to the primary server even if it becomes available. In case the failover server fails, {{ site.product.short_name }} attempts to connect the next failover server in the list in round-robin fashion.
14-
15-
![]({{ site.baseurl}}/assets/images/caution.png) **CAUTION:**
16-
The failover servers must be accessible on the same port as the primary server.
17-
{: .notice--warning}
7+
failover() has the following sub-options:
188

199
### failback()
2010

21-
*Description:* Available only in {{ site.product.name }} version 3.17 and later.
22-
23-
When {{ site.product.short_name }} starts up, it always connects to the primary
24-
server first. In the failover() option there is a possibility to
25-
customize the failover modes.
26-
Depending on how you set the failback() option, {{ site.product.short_name }}
27-
behaves as follows:
28-
29-
- **round-robin mode**: If failback() is not set, {{ site.product.short_name }} does not attempt to return to the primary server even if it becomes available. In case the failover server fails, {{ site.product.short_name }} attempts to connect the next failover server in the list in round-robin fashion.
30-
31-
Example: round-robin mode
32-
33-
In the following example {{ site.product.short_name }} handles the logservers in round-robin fashion if the primary logserver becomes inaccessible (therefore failback() option is not set).
34-
35-
```config
36-
destination d_network {
37-
network(
38-
"primary-server.com"
39-
port(601)
40-
41-
failover( servers("failover-server1", "failover-server2") )
42-
);
43-
};
44-
```
11+
{% include doc/admin-guide/options/failback-modes.md %}
4512

46-
- **failback mode**: If failback() is set, {{ site.product.short_name }} attempts to return to the primary server.
13+
The above described valid failback() sub-option defaults are:
4714

48-
After {{ site.product.short_name }} connects a secondary server during a failover, it sends a probe every tcp-probe-interval() seconds towards the primary server. If the primary logserver responds with a TCP ACK packet, the probe is successful. When the number of successful probes reaches the value set in the successful-probes-required() option, {{ site.product.short_name }} tries to connect the primary server using the last probe.
15+
#### tcp-probe-interval()
4916

50-
**NOTE:** {{ site.product.short_name }} always waits for the result of the last probe before sending the next message. So if one connection attempt takes longer than the configured interval, that is, it waits for connection time out, you may experience longer intervals between actual probes.
51-
{: .notice--info}
17+
| Type:| integer|
18+
|Default:| 60|
5219

53-
Example: failback mode
20+
#### successful-probes-required()
5421

55-
In the following example {{ site.product.short_name }} attempts to return to the primary logserver, as set in the failback() option: it will check if the server is accessible every tcp-probe-interval() seconds, and reconnect to the primary logserver after three successful connection attempts.
56-
57-
```config
58-
destination d_network_2 {
59-
network(
60-
"primary-server.com"
61-
port(601)
62-
failover(
63-
64-
servers("failover-server1", "failover-server2")
65-
failback(
66-
successful-probes-required()
67-
tcp-probe-interval()
68-
)
69-
)
70-
);
71-
};
72-
```
73-
74-
Default value for tcp-probe-interval(): 60 seconds
75-
76-
Default value for successful-probes-required(): 3
77-
78-
**NOTE:** This option is not available for the connection-less UDP protocol,
79-
because in this case the client does not detect that the destination
80-
becomes inaccessible.
81-
{: .notice--info}
22+
| Type:| integer|
23+
|Default:| 3|
8224

8325
#### Example: Specifying failover servers for syslog() destinations
8426

8527
The following example specifies two failover servers for a simple
86-
syslog() destination.
28+
syslog() destination uses the UDP protocol.
8729

8830
```config
8931
destination d_syslog_tcp{
9032
syslog("10.100.20.40"
91-
transport("tcp")
33+
transport("udp")
9234
port(6514)
93-
failover-servers("10.2.3.4", "myfailoverserver")
35+
failover(
36+
servers("10.2.3.4", "myfailoverserver")
37+
)
9438
);
9539
};
9640
```
@@ -103,11 +47,26 @@ destination d_syslog_tls{
10347
network("10.100.20.40"
10448
transport("tls")
10549
port(6514)
106-
failover-servers("10.2.3.4", "myfailoverserver")
50+
failover(
51+
servers("10.2.3.4", "myfailoverserver")
52+
failback(successful-probes-required(2) tcp-probe-interval(10))
53+
)
10754
tls(peer-verify(required-trusted)
10855
ca-dir('/opt/syslog-ng/etc/syslog-ng/keys/ca.d/')
10956
key-file('/opt/syslog-ng/etc/syslog-ng/keys/client_key.pem')
11057
cert-file('/opt/syslog-ng/etc/syslog-ng/keys/client_certificate.pem'))
11158
);
11259
};
11360
```
61+
62+
### servers()
63+
64+
| Type: | list of IP addresses and fully-qualified domain names|
65+
| Default: | empty |
66+
67+
*Description:* Specifies a secondary destination server where log messages are sent if the primary server becomes inaccessible. To list several failover servers, separate the address of the servers with comma. By default, {{ site.product.short_name }} waits for the a server before switching to the next failover server is set in the time-reopen() option.
68+
If failback() is not set, {{ site.product.short_name }} does not attempt to return to the primary server even if it becomes available. In case the failover server fails, {{ site.product.short_name }} attempts to connect the next failover server in the list in round-robin fashion.
69+
70+
![]({{ site.baseurl}}/assets/images/caution.png) **CAUTION:**
71+
The failover servers must be accessible on the same port as the primary server.
72+
{: .notice--warning}

‎doc/_admin-guide/070_Destinations/370_Client_side_failover.md‎

Lines changed: 2 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -16,76 +16,7 @@ configuration and it has a special role. {{ site.product.short_name }} nominates
1616
destination over the failover servers, and handles it as the primary
1717
address.
1818

19-
When {{ site.product.short_name }} starts up, it always connects to the primary server
20-
first. In the failover() option there is a possibility to customize the
21-
failover modes.
22-
23-
Depending on how you set the failback() option, {{ site.product.short_name }} behaves as
24-
follows:
25-
26-
- **round-robin mode**: If failback() is not set, {{ site.product.short_name }} does
27-
not attempt to return to the primary server even if it becomes
28-
available. In case the failover server fails, {{ site.product.short_name }} attempts
29-
to connect the next failover server in the list in round-robin
30-
fashion.
31-
32-
Example: round-robin mode
33-
34-
In the following example {{ site.product.short_name }} handles the logservers in
35-
round-robin fashion if the primary logserver becomes inaccessible
36-
(therefore failback() option is not set).
37-
38-
```config
39-
destination d_network {
40-
network(
41-
"primary-server.com"
42-
port(601)
43-
failover( servers("failover-server1", "failover-server2") )
44-
);
45-
};
46-
```
47-
48-
- **failback mode**: If failback() is set, {{ site.product.short_name }} attempts to
49-
return to the primary server.
50-
51-
After {{ site.product.short_name }} connects a secondary server during a failover,
52-
it sends a probe every tcp-probe-interval() seconds towards the
53-
primary server. If the primary logserver responds with a TCP ACK
54-
packet, the probe is successful. When the number of successful
55-
probes reaches the value set in the successful-probes-required()
56-
option, {{ site.product.short_name }} tries to connect the primary server using the
57-
last probe.
58-
59-
**NOTE:** {{ site.product.short_name }} always waits for the result of the last probe
60-
before sending the next message. So if one connection attempt takes
61-
longer than the configured interval, that is, it waits for
62-
connection time out, you may experience longer intervals between
63-
actual probes.
64-
{: .notice--info}
65-
66-
Example: failback mode
67-
68-
In the following example {{ site.product.short_name }} attempts to return to the
69-
primary logserver, as set in the failback() option: it will check if
70-
the server is accessible every tcp-probe-interval() seconds, and
71-
reconnect to the primary logserver after three successful connection
72-
attempts.
73-
74-
```config
75-
destination d_network_2 {
76-
network(
77-
"primary-server.com"
78-
port(601)
79-
failover(
80-
servers("failover-server1", "failover-server2")
81-
failback(
82-
successful-probes-required()
83-
tcp-probe-interval()
84-
)
85-
)
86-
);
87-
};
88-
```
19+
{% include doc/admin-guide/options/failback-modes.md %}
8920

9021
If {{ site.product.short_name }} is restarted, it attempts to connect the primary
9122
server.
@@ -102,11 +33,7 @@ The primary server and the failover servers must be accessible with the
10233
same communication method: it is not possible to use different
10334
destination drivers or options for the different servers.
10435

105-
**NOTE:** Client-side failover works only for TCP-based connections
106-
(including TLS-encrypted connections), that is, the syslog() and
107-
network() destination drivers (excluding UDP transport).
108-
Client-side failover is not supported in the sql() driver, even though
109-
it may use a TCP connection to access a remote database.
36+
**NOTE:** Client-side failover is not supported in the sql() driver.
11037
{: .notice--info}
11138

11239
For details on configuring failover servers, see

‎doc/_admin-guide/090_Global_options/000_Global_options.md‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -331,6 +331,15 @@ driver.
331331

332332
{% include doc/admin-guide/options/send-time-zone.md %}
333333

334+
## so-passcred()
335+
336+
|Accepted values:| `yes`, `no`|
337+
|Default: | `yes`|
338+
339+
*Description:* Enable {{ site.product.short_name }} to collect credential
340+
information (that is, the `PID`, user ID, and group of the sender process)
341+
for messages received using UNIX domain sockets.
342+
334343
## stats()
335344

336345
Available in {{ site.product.short_name }} 4.1 and later versions, introduced by Axoflow.
@@ -422,16 +431,7 @@ log messages. Set to **0** to disable the STATS messages.
422431
**NOTE:** If a lower value is set to max-dynamics() (or, any limiting value, if this option has not been configured before) and {{ site.product.short_name }} is restarted, the changes are only applied after freq() time has passed. That is, the previously allocated dynamic clusters are only removed after this time.
423432
{: .notice--info}
424433

425-
## so-passcred()
426-
427-
|Accepted values:| `yes`, `no`|
428-
|Default: | `yes`|
429-
430-
*Description:* Enable {{ site.product.short_name }} to collect credential
431-
information (that is, the `PID`, user ID, and group of the sender process)
432-
for messages received using UNIX domain sockets.
433-
434-
## syslog-stats()
434+
### syslog-stats()
435435

436436
| Accepted values:| yes, no, auto|
437437
|Default:| auto|

0 commit comments

Comments
 (0)