To my knowledge, PI System Management Tools is the only PI program where administrators will encounter bitmasks or netmasks. The parts of PI System Management Tools that deal with bitmasks or netmasks are:
- Some tuning parameters (EnableAudit, AutoTrustConfig, Server_AuthenticationPolicy)
- PI Trusts
- PI Firewall
This post explains how bitmasks and netmasks work. This post is intended for PI administrators that do not have a background in IT or computer science.
Before we go any further, I should state that, ideally, this post should have minimal practical application to your PI system. Almost everything in PI that uses bitmasks and netmasks has been superseded. See the table below:
|Feature that uses bitmasks/netmasks||How the feature is superseded|
|AutoTrustConfig||PI Mappings are more secure than PI Trusts. PI Mappings should be used instead of PI Trusts whenever possible. This tuning parameter would ideally be set to 0.|
|Server_AuthenticationPolicy||Ideally, PI Trusts would not be used, and so the slider in the Security Settings can be maxed out, giving this tuning parameter a value of 51.|
|PI Trusts||PI Mappings are more secure than PI Trusts. PI Mappings should be used instead of PI Trusts whenever possible.|
|PI Firewall||The PI Firewall is weak. You are better off using better 3rd-party firewalls.|
This leaves the EnableAudit tuning parameter as the only part of PI that uses bitmasks or netmasks and is not superseded.
Bitmask tuning parameters
The table below tabularizes the descriptions of the tuning parameters whose values are bitmasks. The inconsistent capitalization and poor punctuation are preserved. For clarity, the names of the tuning parameters are underlined in the headers. I will explain the Binary and Expanded Form columns later, so do not worry about them for now.
|Description||Auditing mask, -1 enable the audit of all databases. Masked parameter||Bitmask which controls automatic trust configuration||It is not recommended to edit this field, use the Security Settings plugin for normal usage. Flags for disabling logins.|
|Parameter takes effect…||At startup only||Periodically (once a minute)||At startup|
|Ideal||0||51 (110011 in binary)|
|0||0||0||(No auditing)||NONE||Enable all|
|1||1||2⁰||Point||Loopback||Disable Explicit Login|
|2||10||2¹||Digital Sets||Localhost||Disable explicit logins for users with blank passwords|
|4||100||2²||Attribute Sets||IPaddr||Disable trusts|
|16||10000||2⁴||Point Class||Fully Qualified Domain Name (FQDN)||Disable PI-SDK trust|
|17||10001||2⁴ + 2⁰||LoopBack + FQDN|
|32||100000||2⁵||User||Disable PI-API trusts|
|127||1111111||2⁶ + 2⁵ + 2⁴ + 2³ + 2² + 2¹ + 2⁰||v3.4.370 Compatible|
*Not shown so that the column is smaller and the table doesn't have a horizontal scroll bar. Here are the values:
Keep these tables in mind as we dive into the theory of bitmasks and how to use bitmasks.
Theory of bitmasks
Each setting gets its own digit
Suppose that we have 2 related settings: Setting 1 and Setting 2. Each can have a value of either 0 or 1 (off or on). Rather than have a tuning parameter for each setting, you can use a single number and thus a single tuning parameter to represent both settings. For example, the number 10 can be interpreted as being a value of 1 for Setting 1 and a value of 0 for Setting 2.
Under this system, the only valid values for the tuning parameter are 00, 01, 10, and 11. (Of course, 00 is just 0 and 01 is just 1. I am showing the leading 0s for clarity.) What about 02 – 09? What about 12 – 99? Out of the 100 possible values for a 2-digit number (00 – 99), only 4 are valid for the tuning parameter. If we had even more settings packed into this tuning parameter, there would be more and larger ranges of invalid values. The more possible values we have, the more disk space we need to store the value, so it is best if we do not have any invalid values.
We can take this a step further. Since the tuning parameter has only 4 possible values, we can let these values be the values 0 – 3. Then we interpret the values as follows:
|Tuning Parameter Value||Tuning Parameter Value Under The Previous Representation||Setting 1's Value||Setting 2's Value|
This is obviously not as user-friendly as the previous representation, but it is clearly more space-efficient. Thankfully, there is a way to convert between the 2 representations that does not involve creating such a table. To understand this conversion method, we must have a good understanding of the written representation of numbers.
Numeral systems 101
Earlier, we used each digit of a multi-digit number to carry the value of a different setting. Now, we must review what the digits of numbers mean in general. For example, in the number 234, what do the "2", "3", and "4" each mean? The "2" represents 2 hundred. The "3" represents 3 tens. The "4" represents 4 ones. Recall from grade 4 math that we can write any whole number in its expanded form:
= (2 × 100) + (3 × 10) + (4 × 1)
= (2 × 10²) + (3 × 10¹) + (4 × 10⁰)
When we write a number, each digit represents a power of 10 and is 10 times more than the previous. This is 10 as opposed to any other number is because there are 10 possible values for each digit (0 – 9). When we represent numbers in this way, we are using the base-10, or decimal, numeral system.
However, our tuning parameter settings have only 2 possible values each: 0 and 1. We have seen that while a representation like 101 would be convenient for us, it is not space-efficient, but this is only because we think of 101 as meaning this:
= (1 × 100) + (0 × 10) + (1 × 1)
= (1 × 10²) + (0 × 10¹) + (1 × 10⁰)
However, since each setting has only 2 possible values and is represented by a digit, we can restrict each digit to only 2 possible values. That is, we can instead use the base-2, or binary, numeral system:
= (1 × 2²) + (0 × 2¹) + (1 × 2⁰)
= (1 × 4) + (0 × 2) + (1 × 1)
So the binary number 101 is equal to the decimal number 5, or, more compactly, 101 (bin) = 5 (dec). The calculation above shows how to convert from binary to decimal. I will not cover the conversion from decimal to binary. The main point is that there are different ways of writing the same number, and the reason why each setting for the bitmask tuning parameters is represented by a power of 2 is because it corresponds to a binary digit, also called a bit, hence the term "bitmask".
Using bitmasks in PI System Management Tools
To derive a tuning parameter value, just add together the values that correspond to each setting that you want to be toggled on.
To extract meaning from a tuning parameter in PI System Management Tools, use the Excel function DEC2BIN or an online decimal-to-binary converter to convert the tuning parameter to its binary form. Since each bit corresponds to a setting, you will easily be able to tell which settings are toggled on.
Of course, all of this theory would be totally unnecessary if PI System Management Tools just had a check box for each setting of a tuning parameter.
What about EnableAudit = −1?
The description of EnableAudit says that −1 will enable the audit of all databases. How do negative integers fit into the picture?
You might think that because computers represent everything as bits, then maybe we can use a bit to tell us the sign (+ or −) of an integer. For example, for a 4-bit number, 0001 would be 1 and 1001 would be −1. However, computers do not represent integers this way, partly because there would be 2 values for 0 (0000 = 0 and 1000 = −0 = 0), and partly because this representation makes it complicated add or subtract numbers that cross over 0.
To understand how computers actually handle negative integers, we must first understand overflow and underflow.
Overflow, underflow, and signedness
Suppose that we have only 2 decimal digits. We count: 00, 01, …, 98, 99. What happens if we try to count beyond (i.e. add 1 to) 99? The answer is 100, but since we have only 2 digits, we can keep only the lower 2, and so we get 00. Similarly, if we subtract 1 from 00, we get 99. When we surpass the maximum value that our fixed number of digits can hold, we call it overflow, and, when we go below the minimum value that our fixed number of digits can hold, we call it underflow. Notice that the values form a loop or wheel: the next value of the last value (99) is the first value (00).
…, 97, 98, 99, 00, 01, 02, …
Let us assume that we began with this number wheel. We need to cut the wheel at some point, and the numbers at the ends of our cut represent our minimum and maximum values.
When computers deal with unsigned integers (i.e. integers without a sign, i.e. non-negative integers), the cut occurs where you would expect: between 99 and 00, making 99 the maximum value and 00 the minimum value.
When computers deal with signed integers (i.e. integers that have a + or − sign), the cut occurs between 49 and 50. The numbers are then interpreted like this:
|50||−50 (minimum value)|
|49||49 (maximum value)|
This representation has only 1 value for 0 and makes it easy to cross over 0 for addition and subtraction. Of course, computers count in binary and not decimal, but the idea is the same. Using a 3-bit number as an example:
|Computer Representation||Meaning As A Signed Integer||Meaning As An Unsigned Integer|
|100||−4 (minimum value)|
|000||0||0 (minimum value)|
|011||3 (maximum value)||3|
|111||7 (maximum value)|
You will notice that the 1st bit indicates, but does not explicitly represent, the sign of the number (0 = +, 1 = −). However, the negation of a number (changing the number's sign) is not as straightforward as changing the 1st bit. I will not be covering negation here.
It should now clear why EnableAudit = −1 will enable the audit of all databases. It is because computers represent −1 using a binary number whose digits (bits) are all 1.
−1 = 111…111
In the previous section, we explored the "bit" part of "bitmask". We will now explore the "mask" part.
PI Trusts allow you to specify an IP address and a netmask. For the greatest security with PI Trusts, it is best to use a netmask of 255.255.255.255 so that the PI Trust grants access to only the computer whose IP address was entered. How is the netmask used? And what happens if it is anything other than 255.255.255.255?
First of all, let us convert 255.255.255.255 to binary:
IP addresses can also be converted to binary. For example, the IP address 18.104.22.168 becomes:
The netmask tells us which bits must match between the IP address in the PI Trust and the IP address of the connecting computer for the connecting computer to be granted access to the PI system. Since 255.255.255.255 is a netmask of all 1s, it means that all bits must match.
If we change the netmask to 255.255.255.0 (11111111.11111111.11111111.00000000), then only computers with IP addresses in the range of 22.214.171.124 – 126.96.36.199 would be allowed to connect.
Usually, the netmask is a series of 1s followed by a series of 0s, and so CIDR notation is often used to compactly represent the netmask. For example, 188.8.131.52 with a netmask of 255.255.255.0 can be written as "184.108.40.206 /24", where the number after the "/" represents the number of consecutive leading bits that are 1.
The PI Firewall uses yet another notation to represent netmasks. For example, 10.*.*.* in the PI Firewall represents 10.0.0.0 /8. It will allow only computers with IP addresses in the range of 10.0.0.0 – 10.255.255.255 to connect.
Hopefully, you learned something from this post. If you found this post useful, please review your PI system and try to replace all of your PI Trusts with PI Mappings.
If I missed any applications of bitmasks or netmasks in PI or if I missed any bitmask tuning parameters (perhaps those that are hidden by default), please let me know in the comments.