Recently, a release has required the renaming of user accounts … lots of user accounts. This is not a problem, just change them, but how do we move any reports that had been created in My Folders?
When the user logs in with their new User ID a new folder will be created automatically for them in the catalog to store My Folders and anything that they had previously created will be left behind. We can’t simply copy them across as the ATR file will prevent the new user from even knowing they exist.
So, what is an ATR File?
For each object in the OBIEE Catalog there is the object itself, either a file or directory, and there is an associated ATR file. The ATR file is a binary file that defines access control for an object. The files listed below are an example of the files for a report named My First Report showing the file itself and the associated ATR file.
You can see from the example that the filename of a report is comparable to the name of the report itself, however, with the plus symbol replacing whitespace.
ATR files apply to all objects in the Catalog. For the purposes of this document we will need to look at the ATR file for a user and the ATR file for a report file.
As a binary file we can not simply read an ATR File, but we can convert it to Hex and then view it.
Dissecting the ATR File
When using Linux we can view an ATR file in Hexadecimal with the command below. You can see from this ATR file associated to a report definition that the output begins with a 7-byte line number followed by a colon. Each line shows 32 bytes of hexadecimal code, followed with an ASCII representation.
The first 8-bytes of hex code represent the version of the ATR protocol and can be disregarded for our purposes.
Bytes 9 and 10, 06, are the hex representation for the length of the name of the object, in this case test_0; the hex value 06 is equivalent to 6 in decimal, the length of the string test_0. Each character of the string will be represented in hex with a couple of bytes; therefore, in this case the name of the object will use 12 bytes.
The next 6 bytes, 00 0000, are padding proceeding the hexadecimal representation for the name of the object.
As specified in bytes 9 and 10, the next 12 bytes, 7465 7374 5f30, are the hex representation of the actual name of the object, test_0, this can clearly be seen in the ASCII representation.
From here on in the positions of bytes are not fixed, but relative to matters such as object name.
The next 6 bytes, 0600 01, are padding to proceed the hex representation of the owner of the object.
The Hex ID for the owner of the object follows the padding, here it is 36 ba7b 9f02 fad5 4f; it is always 16 bytes long.
The next section is the access control definition. It begins with, again, 6 bytes of padding, 01 0001; although the padding does hold meaning. The first two bytes indicate that the ACL (Access Control List) contains one entry; the next two are padding; and the next two identify that the first Item in user or group in the list follows.
The following 16 bytes represents the first and only user or group in this ACL, 36 ba7b 9f02 fad5 4f, you will notice that the single user in the list is the same user defined as the owner. This is expected.
The next two bytes, 0f, represent the permissions on this object for the user or group. The permissions can be one of the following values.
The following two bytes give the length of the description of the object, to follow shortly. In this case 0a is hexadecimal for 10 so we know that the description will use 20 bytes; two bytes per character.
This is followed by a further six bytes of padding, 00 0000.
The description then follows, which as defined earlier will be 20 bytes long, 7175 6572 7969 7465 6d31. The description defines the type if you like of object to which the ATR file applies.
In this case the ATR file is ended with a pair of bytes 02 followed by 14 bytes of zero padding. However, if a description existed it would exist between the 02 and zero padding.
Is the ATR file the same for a user object?
If we apply the structure applied to the ATR file for an object of type queryitem1 then we will see that the structure is very similar, although there are differences.
In this example, for a user called demo, we can see that the owner of the object is defined as ff ffff ffff ffff ff, also known as System. And the only user or group in the ACL is 36 ba7b 9f02 fad5 4f, the user defined earlier; this is the user that the ATR file is associated with.
The difference here is that the type definition is missing; you can see that we jump straight from the ACL Permission, through some padding and to the pair of bytes 02. Instead we can verify that this is a User ATR files using the description. 02 is followed by 00 0100 and then two descriptive texts.
The length of the first descriptive text is given as 0b, or 22 bytes; there are 6 bytes of padding and then 22 bytes of the description. This specifies the word UserVersion.
The length of the second descriptive test is given as 08, 16 bytes; there are 6 bytes of padding and then 8 bytes of the description.
The ATR file ends with zero padding.
And what can we do with this information?
To meet our requirement we will copy any existing object files from the source user folder to the new user folder that do not already exist. It is important to only copy files that do not already exist to prevent overwriting objects that have changed.
For each object copied we will need to convert the ATR file to hex, we can then perform a search and replace for known hex user values on the file before converting it back to binary.
We know that we can lookup the hex value for a user by converting the user ATR file to hex and extracting the 16 byte hex code from a known, derived position.
The solution
The screenshot below shows the function that I have written to perform the search and replace of Hex user ID, effectively changing the owner of an object. The function derives the Hex IDs for the new user and previous owner using pre-created functions below.
You can see that this function calls two function getFileATROwner and getUserATRCode. The screenshot below shows the function getFileATROWner, which extracts the Hex ID for the current owner of the object.
The second function, getUserATRCode, extracts the Hex ID for the user to take ownership of the object.
Knowing the Hex IDs for the old and new users allows us to perform the search and replace on the hex conversion of the binary ATR file.
The scripting shown is using bash scripting in linux; this is the platform that the client required help with; my vbs is actually better and the same process is perfectly possible in Windows using either vbs or Windows Powershell.
I hope this was helpful.
When the user logs in with their new User ID a new folder will be created automatically for them in the catalog to store My Folders and anything that they had previously created will be left behind. We can’t simply copy them across as the ATR file will prevent the new user from even knowing they exist.
So, what is an ATR File?
For each object in the OBIEE Catalog there is the object itself, either a file or directory, and there is an associated ATR file. The ATR file is a binary file that defines access control for an object. The files listed below are an example of the files for a report named My First Report showing the file itself and the associated ATR file.
| -rwxr-xr– 1 appobid bin 1307 Jul 28 11:01 My+First+Report -rwxr-xr– 1 appobid bin 62 Jul 28 11:02 My+First+Report.atr |
ATR files apply to all objects in the Catalog. For the purposes of this document we will need to look at the ATR file for a user and the ATR file for a report file.
As a binary file we can not simply read an ATR File, but we can convert it to Hex and then view it.
Dissecting the ATR File
When using Linux we can view an ATR file in Hexadecimal with the command below. You can see from this ATR file associated to a report definition that the output begins with a 7-byte line number followed by a colon. Each line shows 32 bytes of hexadecimal code, followed with an ASCII representation.
Example Hex converstion of Report ATR File
Bytes 9 and 10, 06, are the hex representation for the length of the name of the object, in this case test_0; the hex value 06 is equivalent to 6 in decimal, the length of the string test_0. Each character of the string will be represented in hex with a couple of bytes; therefore, in this case the name of the object will use 12 bytes.
The next 6 bytes, 00 0000, are padding proceeding the hexadecimal representation for the name of the object.
As specified in bytes 9 and 10, the next 12 bytes, 7465 7374 5f30, are the hex representation of the actual name of the object, test_0, this can clearly be seen in the ASCII representation.
From here on in the positions of bytes are not fixed, but relative to matters such as object name.
The next 6 bytes, 0600 01, are padding to proceed the hex representation of the owner of the object.
The Hex ID for the owner of the object follows the padding, here it is 36 ba7b 9f02 fad5 4f; it is always 16 bytes long.
The next section is the access control definition. It begins with, again, 6 bytes of padding, 01 0001; although the padding does hold meaning. The first two bytes indicate that the ACL (Access Control List) contains one entry; the next two are padding; and the next two identify that the first Item in user or group in the list follows.
The following 16 bytes represents the first and only user or group in this ACL, 36 ba7b 9f02 fad5 4f, you will notice that the single user in the list is the same user defined as the owner. This is expected.
The next two bytes, 0f, represent the permissions on this object for the user or group. The permissions can be one of the following values.
- FF – Full Control
- 0F – Change/Modify
- 03 – Read
- 02 – Traverse
- 00 – No Access
The following two bytes give the length of the description of the object, to follow shortly. In this case 0a is hexadecimal for 10 so we know that the description will use 20 bytes; two bytes per character.
This is followed by a further six bytes of padding, 00 0000.
The description then follows, which as defined earlier will be 20 bytes long, 7175 6572 7969 7465 6d31. The description defines the type if you like of object to which the ATR file applies.
In this case the ATR file is ended with a pair of bytes 02 followed by 14 bytes of zero padding. However, if a description existed it would exist between the 02 and zero padding.
Is the ATR file the same for a user object?
If we apply the structure applied to the ATR file for an object of type queryitem1 then we will see that the structure is very similar, although there are differences.
An ATR File for a web user account
The difference here is that the type definition is missing; you can see that we jump straight from the ACL Permission, through some padding and to the pair of bytes 02. Instead we can verify that this is a User ATR files using the description. 02 is followed by 00 0100 and then two descriptive texts.
The length of the first descriptive text is given as 0b, or 22 bytes; there are 6 bytes of padding and then 22 bytes of the description. This specifies the word UserVersion.
The length of the second descriptive test is given as 08, 16 bytes; there are 6 bytes of padding and then 8 bytes of the description.
The ATR file ends with zero padding.
And what can we do with this information?
To meet our requirement we will copy any existing object files from the source user folder to the new user folder that do not already exist. It is important to only copy files that do not already exist to prevent overwriting objects that have changed.
For each object copied we will need to convert the ATR file to hex, we can then perform a search and replace for known hex user values on the file before converting it back to binary.
We know that we can lookup the hex value for a user by converting the user ATR file to hex and extracting the 16 byte hex code from a known, derived position.
The solution
The screenshot below shows the function that I have written to perform the search and replace of Hex user ID, effectively changing the owner of an object. The function derives the Hex IDs for the new user and previous owner using pre-created functions below.
Script to change the owner of an object
We need to get the unique hex id for the File owner in the atr file
We also need to get the unique hex id for the new object owner
The scripting shown is using bash scripting in linux; this is the platform that the client required help with; my vbs is actually better and the same process is perfectly possible in Windows using either vbs or Windows Powershell.
I hope this was helpful.
No comments:
Post a Comment