forked from mboldt/docs-tiledev
-
Notifications
You must be signed in to change notification settings - Fork 0
/
migrating-syslog-configuration.html.md.erb
149 lines (130 loc) · 5.89 KB
/
migrating-syslog-configuration.html.md.erb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
---
title: Migrating Existing Syslog Configuration to Ops Manager
owner: Ops Manager
---
This topic explains how to migrate existing syslog properties that are defined by a tile into the
syslog form provided in Ops Manager v2.5 and later.
By enabling the Ops Manager syslog feature, Ops Manager:
* Provides your tile with its own syslog form
* Ensures that the syslog BOSH release is automatically injected into the instance groups of your product
* Includes syslog configuration properties when Ops Manager injects the syslog release into your product
## <a id="syslog-data-model"></a>Syslog Data Model
The following table lists the Ops Manager syslog parameters that you can migrate your existing
configurations to.
<table class="nice">
<tr>
<th width="175">Syslog parameter</th>
<th>Data Type</th>
<th width="150">Required</th>
<th>Notes</th>
</tr>
<tr>
<td><code>enabled</code></td>
<td>boolean</td>
<td>No</td>
<td> Defaults to <code>false</code></td>
</tr>
<tr>
<td><code>address</code></td>
<td>string</td>
<td>Yes</td>
<td>The address or host for the syslog server. <br>Must be a valid network address</td>
</tr>
<tr>
<td><code>port</code></td>
<td>integer</td>
<td>Yes</td>
<td>The port on which the syslog server listens</td>
</tr>
<tr>
<td><code>transport_protocol</code></td>
<td>string</td>
<td>No</td>
<td>The transport protocol used to send syslog messages to the server.
<br>Valid values are <code>tcp</code> and <code>udp</code>. Defaults to <code>tcp</code></td>
</tr>
<tr>
<td><code>tls_enabled</code></td>
<td>boolean</td>
<td>No</td>
<td>Send logs encrypted to syslog server via TLS. Defaults to <code>false</code></td>
</tr>
<tr>
<td><code>permitted_peer</code></td>
<td>boolean</td>
<td>No, unless <code>tls_enabled</code> is <code>true</code></td>
<td> Defaults to <code>false</code>.</td>
</tr>
<tr>
<td><code>ssl_ca_certificate</code></td>
<td>string</td>
<td>No, unless <code>tls_enabled</code> is <code>true</code></td>
<td>Must be a valid certificate<br>
Defaults to <code>null</code>.</td>
</tr>
<tr>
<td><code>queue_size</code></td>
<td>integer</td>
<td>No</td>
<td>The number of log messages the buffer holds before dropping messages. A larger buffer size
might overload the system. Defaults to <code>100000</code></td>
</tr>
<tr>
<td><code>forward_debug_logs</code></td>
<td>boolean</td>
<td>No</td>
<td>Defaults to <code>false</code></td>
</tr>
<tr>
<td><code>custom_rsyslog_configuration</code></td>
<td>text</td>
<td>No</td>
<td>Additional configuration for rsyslog written in the rainerscript syntax.
For example, <code>if ($app-name startswith "exampleComponent") then stop</code>
can be used to drop all traffic from a particular component.
The entered configuration is applied before the forwarding rule.</td>
</tr>
</table>
## <a id="javascript"></a> Use the JavaScript Migration Process
Tile authors can write a JavaScript migration to move their existing syslog properties into the
syslog form provided by Ops Manager. After a successful migration, Ops Manager presents the
migrated syslog properties in the Syslog form of the tile.
1. Set the `opsmanager_syslog` property to `true` in your `metadata.yml`.
For more information, see [opsmanager_syslog](./property-template-references.html#syslog-flag).
1. To write your JavaScript migration, use the following example as a template:
```js
exports.migrate = function(input) {
input.syslog_configuration = {
enabled: true,
address: input.properties['.PROPERTY-REFERENCE.EXAMPLE-ADDRESS'],
port: input.properties['.PROPERTY-REFERENCE.EXAMPLE-PORT'],
transport_protocol: input.properties['.PROPERTY-REFERENCE.EXAMPLE-PROTOCOL']
};
return input;
};
```
In the code block above, replace the example text as follows:
* `PROPERTY-REFERENCE`: Replace with the property reference that corresponds to the metadata
file, such as `properties`.
For more information about migrating properties, see [Tile Upgrades](./tile-upgrades.html#import).
* `EXAMPLE-ADDRESS`: Replace with the property name of the address.
* `EXAMPLE-PORT`: Replace with the property name of the port.
* `EXAMPLE-PROTOCOL`: Replace with the property name of the transport protocol.
1. Save the JavaScript file to the `PRODUCT/migrations/v1` directory of your `.pivotal` file.
1. Remove the following:
* From your product template, `form_types` that allow operators to configure tile-specific syslog configuration
* From your tile, the syslog BOSH release.
* From your deployment manifest, syslog configuration properties.
1. To ensure that operators do not try to update syslog configuration properties with no outward
functionality, mark all existing syslog configuration properties in your product as non-configurable.
1. Update the description for the deprecated properties to state that they are deprecated and are no
longer used to configure the syslog.
1. Run a test deploy of your tile by doing the procedures in [Testing Tiles](./testing.html).
1. To ensure that your syslog properties were successfully migrated into the Ops Manager syslog
configuration, do one of the following:
* View the configurations in the **Syslog** pane in Ops Manager **Settings** page.
* View your syslog properties using the `syslog_configuration` Ops Manager API endpoint.
For more information about the `syslog_configuration` API endpoint, see
[Retrieving syslog configuration for a product](https://docs.pivotal.io/platform/2-10/opsman-api/#tag/Syslog-Configuration/paths/~1api~1v0~1staged~1products~1{product_guid}~1syslog_configuration/get).
<p class="note"><strong>Note:</strong> In the next version of your product, remove
the deprecated syslog configuration properties.</p>