Kenneth_Barber

PI Theory: Bitmasks & netmasks explained

Blog Post created by Kenneth_Barber Champion on Aug 7, 2020

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.

 

My recommendation

 

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/netmasksHow the feature is superseded
AutoTrustConfigPI 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_AuthenticationPolicyIdeally, 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 TrustsPI Mappings are more secure than PI Trusts. PI Mappings should be used instead of PI Trusts whenever possible.
PI FirewallThe 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.

 

Bitmasks

 

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.

 

ValueBinaryExpanded FormEnableAuditAutoTrustConfigServer_AuthenticationPolicy
TabGeneralSecuritySecurity
DescriptionAuditing mask, -1 enable the audit of all databases. Masked parameterBitmask which controls automatic trust configurationIt is not recommended to edit this field, use the Security Settings plugin for normal usage. Flags for disabling logins.
Parameter takes effect…At startup onlyPeriodically (once a minute)At startup
Ideal051 (110011 in binary)
Default010
Minimum-100
Maximum2,147,483,64725563
000(No auditing)NONEEnable all
112PointLoopbackDisable Explicit Login
2102¹Digital SetsLocalhostDisable explicit logins for users with blank passwords
4100Attribute SetsIPaddrDisable trusts
810002³HostnameDisable Mappings
16100002⁴Point ClassFully Qualified Domain Name (FQDN)Disable PI-SDK trust
17100012⁴ + 2LoopBack + FQDN
321000002UserDisable PI-API trusts
6410000002⁶Group
12711111112⁶ + 2⁵ + 2⁴ + 2³ + 2² + 2¹ + 2v3.4.370 Compatible
128100000002⁷Trust
2561000000002⁸Module
51210000000002⁹Heading
1024100000000002¹⁰TransferRecord
2048100000000000¹Campaign
409610000000000002¹²Batch
8192100000000000002¹³UnitBatch
163841000000000000002¹⁴Server
3276810000000000000002¹⁵Collective
65536100000000000000002¹⁶Identity
131072*2¹⁷Identity Mapping
268435456*2²⁸Snapshot
536870912*2²⁹Archive
1073741824*2³⁰DBsecurity

*Not shown so that the column is smaller and the table doesn't have a horizontal scroll bar. Here are the values:

ValueBinary
131072100000000000000000
26843545610000000000000000000000000000
536870912100000000000000000000000000000
10737418241000000000000000000000000000000

 

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 ValueTuning Parameter Value Under The Previous RepresentationSetting 1's ValueSetting 2's Value
00000
10101
21010
31111

 

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:

 

234

= (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:

 

101

= (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:

 

101

= (1 × 2²) + (0 × 2¹) + (1 × 2⁰)

= (1 × 4) + (0 × 2) + (1 × 1)

= 5

 

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:

 

Computer RepresentationMeaning
50−50 (minimum value)
51−49
98−2
99−1
000
011
022
4848
4949 (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 RepresentationMeaning As A Signed IntegerMeaning As An Unsigned Integer
100−4 (minimum value)
101−3
110−2
111−1
00000 (minimum value)
00111
01022
0113 (maximum value)3
1004
1015
1106
1117 (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

 

Netmasks

 

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:

11111111.11111111.11111111.11111111

 

IP addresses can also be converted to binary. For example, the IP address 15.7.3.1 becomes:

00001111.00000111.00000011.00000001

 

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 15.7.3.0 – 15.7.3.255 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, 15.7.3.1 with a netmask of 255.255.255.0 can be written as "15.7.3.1 /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.

 

Conclusion

 

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.

Outcomes