Rev 1267 | Show entire file | Regard whitespace | Details | Blame | Last modification | View Log | RSS feed
| Rev 1267 | Rev 1269 | ||
|---|---|---|---|
| Line 4... | Line 4... | ||
| 4 | 4 | ||
| 5 | ## What is a mask code? |
5 | ## What is a mask code? |
| 6 | 6 | ||
| 7 | A "mask code" gives information about the log event. |
7 | A "mask code" gives information about the log event. |
| 8 | It contains: |
8 | It contains: |
| 9 | 1. The severity (info, warning, error, critical) |
9 | 1. The severity (success, info, warning, error, critical) |
| 10 | 2. In which logbook(s) the event shall be placed |
10 | 2. In which logbook(s) the event shall be placed |
| 11 | 11 | ||
| 12 | Example: |
12 | Example: |
| 13 | Let's imagine the following event: |
13 | Let's imagine the following event: |
| 14 | 14 | ||
| Line 39... | Line 39... | ||
| 39 | 39 | ||
| 40 | A mask code begins with `V2:` |
40 | A mask code begins with `V2:` |
| 41 | 41 | ||
| 42 | ### Components |
42 | ### Components |
| 43 | 43 | ||
| 44 | A mask code can have multiple components which are split into single codes using `+` or `/`, e.g. `OID(x)+RA(x)` would |
44 | A mask code can have multiple components which are split into single codes using `+`, e.g. `OID(x)+OIDRA(x)` would |
| 45 | be split to `OID(x)` and `RA(x)` which would result in the message being placed in the logbook of OID x, |
45 | be split to `OID(x)` and `OIDRA(x)` which would result in the message being placed in the logbook of OID x, |
| 46 | and the logbook of the RA owning OID x. |
46 | and the logbook of the RA owning OID x. |
| 47 | 47 | ||
| 48 | ### Severity |
48 | ### Severity |
| 49 | 49 | ||
| 50 | At the beginning of each mask code, you must define a severity, which is written in square brackets. |
50 | At the beginning of each mask code, you must define a severity, which is written in square brackets. |
| 51 | 51 | ||
| 52 | Valid severities: |
52 | Valid severities: |
| 53 | - `[OK]`: Rule of thumb: YOU have done something and it was successful. |
53 | - `[OK]`: Rule of thumb: You have done something and it was successful. |
| 54 | - `[INFO]`: Rule of thumb: Someone else has done something (that affects you) and it was successful. |
54 | - `[INFO]`: Rule of thumb: Someone else has done something (that affects you) and it was successful. |
| 55 | - `[WARN]`: Rule of thumb: Something happened (probably someone did something) and it affects you. |
55 | - `[WARN]`: Rule of thumb: Something happened (probably someone did something) and it affects you. |
| 56 | - `[ERR]`: Rule of thumb: Something failed (probably someone did something) and it affects you. |
56 | - `[ERR]`: Rule of thumb: Something failed (probably someone did something) and it affects you. |
| 57 | - `[CRIT]`: Rule of thumb: Something happened (probably someone did something) which is not an error, but some critical situation (e.g. hardware failure), and it affects you. |
57 | - `[CRIT]`: Rule of thumb: Something happened (probably someone did something) which is not an error, but some critical situation (e.g. hardware failure), and it affects you. |
| 58 | 58 | ||
| 59 | If you have a mask code with multiple components, you don't have to place the severity for each component. |
59 | If you have a mask code with multiple components, you don't have to place the severity for each component. |
| 60 | You can just leave it at the beginning. For example, `[WARN]OID(x)+RA(x)` is equal to `[WARN]OID(x)+[WARN]RA(x)`. |
60 | You can just leave it at the beginning. For example, `[WARN]OID(x)+OIDRA(x)` is equal to `[WARN]OID(x)+[WARN]OIDRA(x)`. |
| 61 | You can also put different severities for the components, e.g. `[INFO]OID(x)+[WARN]RA(x)` |
61 | You can also put different severities for the components, e.g. `[INFO]OID(x)+[WARN]OIDRA(x)` |
| 62 | would be an informative message (`INFO`) for the OID, but a warning (`WARN`) for the RA. |
62 | would be an informative message (`INFO`) for the OID, but a warning (`WARN`) for the RA. |
| 63 | 63 | ||
| 64 | ### Online/Offline dependency |
64 | ### Online/Offline dependency |
| 65 | 65 | ||
| 66 | If you want to make the logging event dependent on whether |
66 | If you want to make the logging event dependent on whether |
| 67 | the target (`A`, `RA`, `OIDRA`, `SUPOIDRA`) matches the currently |
67 | the target (`A`, `RA`, `OIDRA`, `SUPOIDRA`) matches the currently |
| 68 | logged-in user or not, write `[S1/S2]` where `S1` is the severity |
68 | logged-in user or not, use the severity `[S1/S2]` where `S1` is the severity |
| 69 | when the logged-in user is the target |
69 | when the logged-in user is the target |
| 70 | and `S2` is the severity when the user is not logged in or |
70 | and `S2` is the severity when the user is not logged in or |
| 71 | logged in as a user not matching the target. |
71 | logged in as a user not matching the target. |
| 72 | 72 | ||
| 73 | With this technique, you can achieve that the RA gets warned if an admin or superior RA |
73 | With this technique, you can achieve that the RA gets warned if an admin or superior RA |
| 74 | changed some of their OIDs without their knowledge, |
74 | changed some of their OIDs without their knowledge, |
| 75 | but receives a success message if they did the change themselves. |
75 | but receives a success message if they did the change themselves. |
| 76 | 76 | ||
| 77 | Example: `[OK/WARN]RA(x)+[OK/INFO]A` means that there are two log messages generated: |
77 | Example: `[OK/WARN]RA(x)+[OK/INFO]A` means that there are two log messages generated: |
| 78 | - Message 1: If the currently logged-in user (performing the action) |
78 | - Message 1 (`[OK/WARN]RA(x)`): If the currently logged-in user (performing the action) |
| 79 | is RA "x", then it is a success message (`OK`) for them, |
79 | is RA "x", then it is a success message (`OK`) for them, |
| 80 | otherwise it is a warning (`WARN`) for them, |
80 | otherwise it is a warning (`WARN`) for them, |
| 81 | i.e. they get warned that someone else (admin or superior RA) |
81 | i.e. they get warned that someone else (admin or superior RA) |
| 82 | has changed something without their knowledge. |
82 | has changed something without their knowledge. |
| 83 | - Message 2: If the currently logged-in user (performing the action) |
83 | - Message 2 (`[OK/INFO]A`): If the currently logged-in user (performing the action) |
| 84 | is the administrator of the system, then it is a success message (`OK`) |
84 | is the administrator of the system, then it is a success message (`OK`) |
| 85 | for them, otherwise it is an informative message (`INFO`) for them, |
85 | for them, otherwise it is an informative message (`INFO`) for them, |
| 86 | i.e. the admin gets informed that a RA has done something. |
86 | i.e. the admin gets informed that a RA has done something. |
| 87 | 87 | ||
| 88 | You can use the special severity `NONE` to achieve that an event is |
88 | You can use the special severity `NONE` to achieve that an event is |
| 89 | not logged, so `NONE/...` means that the event is not logged |
89 | not logged, so `[NONE/...]` means that the event is not logged |
| 90 | if the currently logged-in user matches the target, |
90 | if the currently logged-in user matches the target, |
| 91 | and `.../NONE` means that the event is not logged if the user |
91 | and `[.../NONE]` means that the event is not logged if the user |
| 92 | is not logged in or logged in as a user not matching the target. |
92 | is not logged in or logged in as a user not matching the target. |
| 93 | 93 | ||
| 94 | Example: `[OK/NONE]RA(x)+[OK/NONE]A` could be used |
94 | Example: `[OK/NONE]RA(x)+[OK/NONE]A` could be used |
| 95 | to give the RA or the admin a success message (`OK`) |
95 | to give the RA or the admin a success message (`OK`) |
| 96 | for their action, but the admin won't be notified if the |
96 | for their action, but the admin won't be notified if the |
| 97 | RA has changed it, and the RA won't be notified if the |
97 | RA has changed it, and the RA won't be notified if the |
| 98 | admin changed it. An Exception is if the user is logged in |
98 | admin changed it. An Exception is if the user is logged in |
| 99 | with both accounts (RA and admin) at the same time (which is |
99 | with both accounts (RA and admin) at the same time (which is |
| 100 | possible with OIDplus), then two log messages would be generated. |
100 | possible with OIDplus), then two log messages would be generated. |
| 101 | 101 | ||
| 102 | The severities `[NONE]` and `[NONE/NONE]` are invalid, because they are meaningless. |
102 | The severities `[NONE]` and `[NONE/NONE]` are invalid, |
| - | 103 | because they are meaningless (resulting in nothing being logged at all). |
|
| 103 | 104 | ||
| 104 | The online/offline dependency is only possible for the types `OIDRA`, `SUPOIDRA`, `RA`, and `A`, |
105 | The online/offline dependency is only possible for the types `OIDRA`, `SUPOIDRA`, `RA`, and `A`, |
| 105 | but not for `OID` or `SUPOID`. |
106 | but not for `OID` or `SUPOID`. |
| 106 | 107 | ||
| 107 | ### Valid types |
108 | ### Valid types |