A Thank You, and a question about ADMX files.

[jobisoft]

Foremost: Thank you for the work you put into documenting the policies. I do the same for Thunderbird, and I know how much work that is.

In the past we have simply cloned your policies, re-branded them to Thunderbird, removed policies we do not support and then added our own policies on top. However, this became more and more fragile, since we did not port all the actual changes, but got the updated documentation.

I finally decided to create YAML files for all the policies we support, and completely generate our policy documentation. I should have talked with you about this earlier, since you probably have something similar in place.

If you would like to have a peak:

• project description
• generated documentation
• YAML file
• parsing code to generate the initial YAML files from your rendered documentation

We now generate the README files and PLIST files from our YAML config (which will soon be moved out of the repo into our comm-* trees), but not yet the ADML/ADMX files. Before I start working on that final part of the project, I wanted to ask if you have any related generator code or information which I could use as a starting point.

Thanks again for your work on the policy documentation.

[mkaply]

I don't have anything in place. I do it all manually.

I've always wanted to build something to generate things, but I just haven't had the time.

I also wanted to move the translations into something that can live in Pontoon.

Ideally, it would read the documentaton from the schema and other files in Firefox search to generate the basic stuff...

At some point, we probably should work closer on policies in Thunderbird.

[jobisoft]

Ok, thanks for your feedback. I will start working on the admx/adml file generator now. I briefly discussed with my team how to handle translations, and we decided to put a fluent file in the documentation folder, and have that translated like any other fluent file in the tree. The generator script will pull the translated strings from http://github.com/thunderbird/thunderbird-l10n/.

I think this should work in a similar way with Firefox. I'd like to keep this issue open until everything is up and running, and then contact you here so you can take a look (if you'd like).

I'd also like to be able to ask questions about the ADMX/ADML file format here if I get stuck—if that's okay with you.

[mkaply]

That would be great.

And please, ask away.

I'll help in any way I can.

[jobisoft]

The key attribute of policy elements can be left out, if all child elements have keys, correct?
https://github.com/mozilla/policy-templates/blob/master/windows/firefox.admx

Otherwise, I struggle to find a pattern in the used (outer) keys in these policy entries:

    <policy
        name="Authentication_SPNEGO"
        class="Both"
        displayName="$(string.Authentication_SPNEGO)"
        key="Software\Policies\Mozilla\Firefox\Authentication\SPNEGO"
        explainText="$(string.Authentication_SPNEGO_Explain)"
        presentation="$(presentation.Authentication)">
      <parentCategory ref="Authentication"/>
      <supportedOn ref="SUPPORTED_FF60"/>
      <elements>
        <list id="Authentication" key="Software\Policies\Mozilla\Firefox\Authentication\SPNEGO" valuePrefix=""/>
      </elements>
    </policy>

vs

    <policy
        name="Cookies_Allow"
        class="Both"
        displayName="$(string.Allow)"
        explainText="$(string.Cookies_Allow_Explain)"
        key="Software\Policies\Mozilla\Firefox"
        presentation="$(presentation.Permissions)">
      <parentCategory ref="Cookies"/>
      <supportedOn ref="SUPPORTED_FF60"/>
      <elements>
        <list id="Permissions" key="Software\Policies\Mozilla\Firefox\Cookies\Allow" valuePrefix=""/>
      </elements>
    </policy>

[mkaply]

I don't know the answer to that :).

Most of what I did was just copying Chrome.

I think the important thing would be to make sure one migrates to the other. I'll do some testing and let you know.

[jobisoft]

It looks like the ADMX file needs to have key attribute in the policy node, even if it is not used.

I have now generated our ADMX files with correct syntax, which is accepted by the group police editor. It is possible to change values and the correct registry keys are updated (including support for required and expandable). \o/

Our documentation is also fully generated now.

As I mentioned before, we are using a YAML file, which has all the information to generate the documentation and the templates. I currently specify the individual entries for gpo, intune, plist and json:

policies:
  AppAutoUpdate:
    toc: 'Enable or disable automatic application update.'
    description: |
      Enable or disable **automatic** application update.

      If set to true, application updates are installed without user approval within Thunderbird. The operating system might still require approval.

      If set to false, application updates are downloaded but the user can choose when to install the update.

      If you have disabled updates via `DisableAppUpdate`, this policy has no effect.
    cck2Equivalent:
    preferencesAffected:
      - app.update.auto
    gpo:
      - key: 'Software\Policies\Mozilla\Thunderbird\AppAutoUpdate'
        type: 'REG_DWORD'
        value: '0x1 | 0x0'
    intune:
      - oma-uri: './Device/Vendor/MSFT/Policy/Config/Thunderbird~Policy~thunderbird/AppAutoUpdate'
        type: 'string'
        value: '<enabled/> | <disabled/>'
    plist: |
      <dict>
        <key>AppAutoUpdate</key>
        <true/> | <false/>
      </dict>
    json: |
      {
        "policies": {
          "AppAutoUpdate": true | false
        }
      }

It is however possible, that the entries for gpo, intue, plist and json could be generated from a common base config. The only special cases are gpo entries with type REG_MULTI_SZ. In all the currently implemented policies, the value field for REG_MULTI_SZ is a JSON-styled data. If that assumption is a rule and those value fields will always be JSON-styled data, the entries for intue, plist and json can be fully generated from the gpo entry, and the YAML file can be reduced to something like this:

policies:
  AppAutoUpdate:
    toc: 'Enable or disable automatic application update.'
    description: |
      Enable or disable **automatic** application update.

      If set to true, application updates are installed without user approval within Thunderbird. The operating system might still require approval.

      If set to false, application updates are downloaded but the user can choose when to install the update.

      If you have disabled updates via `DisableAppUpdate`, this policy has no effect.
    cck2Equivalent:
    preferencesAffected:
      - app.update.auto
    entries:
      - key: 'AppAutoUpdate'
        type: 'boolean' // others will be `string`, `expandable_string`, `integer`, `json`

This reduction would help with adding support for localization. This is what we need:

• categories
• a title for each entry (we group multiple entries under the same policy, for example ContentAnalysis
• a description (used as ADMX explain) for each entry
• if a policy has only one entry (for example the shown AppAutoUpdate policy), the "global" toc and description fields for the documentation are identical to the entry's title and description - it should be possible to re-use them.

This is how a config with localization support could look like:

policies:
  AppAutoUpdate:
    cck2Equivalent:
    preferencesAffected:
      - app.update.auto
    l10n-category-id: 'category-something-title'
    entries:
      - key: 'AppAutoUpdate'
        type: 'boolean'
        l10n-title-id: 'AppAutoUpdate-title'
        l10n-description-id: 'AppAutoUpdate-description'

This policy entry has no toc or description field, and the documentation re-uses the strings from the single entry below entries.

A policy with multiple entries could look like so (in this example the l10n id fields do not contain the fluent id, but the actual string, to better showcase the scenario, without the need to show the fluent file as well):

  DisableSecurityBypass:
    toc: 'Prevent the user from bypassing security in certain cases.'
    description: |
      Prevent the user from bypassing security in certain cases.

      `InvalidCertificate` prevents adding an exception when an invalid certificate is shown.

      `SafeBrowsing` prevents selecting "ignore the risk" and visiting a harmful site anyway.

      These policies only affect what happens when an error is shown, they do not affect any settings in preferences.
    cck2Equivalent:
    preferencesAffected:
      - security.certerror.hideAddException
      - browser.safebrowsing.allowOverride
    l10n-category-id: 'Something'
    entires:
      - key: 'DisableSecurityBypass\InvalidCertificate'
        type: 'boolean'
        l10n-title-id: 'Prevent the user from adding an exception when an invalid certificate is shown'
        l10n-description-id: 'Prevents adding an exception when an invalid certificate is shown.'
      - key: 'DisableSecurityBypass\SafeBrowsing'
        type: 'boolean'
        l10n-title-id: 'Prevent the user from selecting "ignore the risk" and visiting a harmful site anyway'
        l10n-description-id: 'Prevents selecting "ignore the risk" and visiting a harmful site anyway.'

The localization would happen through the normal translation process, since the strings are in a normal fluent file (in the tree). Once they have been translated, the generator script can pick up the available translations, and generate the localized ADML files. This approach would have the same limitation as desktop strings: it is not possible to update them. Instead, a new string id has to be used, and the entire string has to be translated again. I cannot say how often you changed descriptions and if that will be too much work for our translators. However, I do not see a better approach.

I would be interested in your feedback:

• do you see issues with this localization approach?
• would you keep specifying the individual configs for gpo, intue, plist and json, or would you go for a common base config?
• would you automatically include the individual descriptions from the entries in the global description? In the above example, the global description field for the DisableSecurityBypass policy would not need to include the two explanations for InvalidCertificate and SafeBrowsing - they would be included automatically (probably as a table at the end)
• would you localize the toc and description fields as well, going for a fully localized documentation?

[mkaply]

So the main issue I have is that the ADML files have a very different documentation style than the main README (Mainly because I was copying the style of a typical ADML template) which is very different than what is in regular documentaton.
I'm not sure what to do about that.

I would much rather go with a common base config, but I'm not sure from your yaml how you can generate all the correct things we need.

Looking at a policy like this for instance:

    <policy name="P_DisableSecurityBypass_SafeBrowsing" class="Both" displayName="$(string.DisableSecurityBypass_SafeBrowsing)" explainText="$(string.DisableSecurityBypass_SafeBrowsing_Explain)" key="Software\Policies\Mozilla\Firefox\DisableSecurityBypass" valueName="SafeBrowsing">
      <parentCategory ref="firefox"/>
      <supportedOn ref="SUPPORTED_FF60"/>
      <enabledValue>
        <decimal value="1"/>
      </enabledValue>
      <disabledValue>
        <decimal value="0"/>
      </disabledValue>
    </policy>

The OMA URI

./Device/Vendor/MSFT/Policy/Config/Firefox~Policy~firefox/P_DisableSecurityBypass_SafeBrowsing

is heavily dependent on the internal stucture of the policy (including categories)

would you automatically include the individual descriptions from the entries in the global description? In the above example, the global description field for the DisableSecurityBypass policy would not need to include the two explanations for InvalidCertificate and SafeBrowsing - they would be included automatically (probably as a table at the end)

They need to be separated because there are three entries in the ADMX file.

would you localize the toc and description fields as well, going for a fully localized documentation?

Are you only referring to the description in the MD?

I'm mainly concerned about translating the ADML, I'm not as concerned about translating the markdown. Maybe I'm wrong?

[jobisoft]

Thanks for your feedback. Do I see it correct, that you are also interested in moving towards a generator approach?

Localization

I'm mainly concerned about translating the ADML, I'm not as concerned about translating the markdown. Maybe I'm wrong?

That is the central question. Since we localize the ADML files, should we also think about localizing the markdown of the public documentation, if the extra effort is acceptable? I am raising this because I think some of the strings used in the ADML file could also be used in the markdown documentation.

would you automatically include the individual descriptions from the entries in the global description? In the above example, the global description field for the DisableSecurityBypass policy would not need to include the two explanations for InvalidCertificate and SafeBrowsing - they would be included automatically (probably as a table at the end)

They need to be separated because there are three entries in the ADMX file.

So the main issue I have is that the ADML files have a very different documentation style than the main README (Mainly because I was copying the style of a typical ADML template) which is very different than what is in regular documentaton.
I'm not sure what to do about that.

I would keep them as three separate entries in the YAML file / fluent file, so that we can generate the ADML file correctly. When generating the markdown, I would merge the individual strings from the different entries to make up the markdown documentation. The markdown description would consist of an "introduction", which is not used in ADML files, followed by a 2-column table with the name of the sub-entries alongside their "explain" strings.

A good example is the DisableSecurityBypass policy. With this approach, we do not need to duplicate the descriptions for InvalidCertificate and SafeBrowsing in the description YAML field, which is used to generate the markdown for the public documentation, but we could pull these from the fluent file "explain" entries for InvalidCertificate and SafeBrowsing, currently primarily used in ADML file.

The documentation for the DisabledCyphers policy would also benefit from it.

This approach dies, if there are cases where the ADML "explain" strings need to be different from the "explain" strings used in the markdown for the public documentation.

There are two edge cases:

• single entries like AppAutoUpdate: They do not need an additional "introduction" to their markdown documentation like policies with multiple sub-entries, they simply use the ADML explain string of the single entry as their markdown documentation.
• REG_MULTI_SZ : It would still fit. For example, the Handlers policy. There are no sub-entries, it is just Handlers. The ADML "explain" string for Handlers needs to talk about the internal JSON structure, like mimeTypes, schemes etc. The markdown documentation needs the same information, which could again be pulled from the ADML explain string, just like the previously mentioned single-entry-edge-case.

OMA-URI

I am still having a large knowledge deficit here. I don't even know how to test an OMA-URI and I do not know if the URIs we list in our documentation actually work.

• Where does the P_ prefix come from in your DisableSecurityBypass policy, which does not seem to be present in any of the GPO, PLIST and JSON entries?
• Or the _Enum suffix in the DisplayBookmarksToolbar policy?
• Is there an algorithm to come up with the correct URI?
• Are PLIST and JSON entries also at risk to have non-standard entries? If not, we could only specify the OMA-URI individually and have GPO, PLIST and JSON entries be generated from a common base config
• But we would still be left with a knowledge deficit, because after finishing this generator project I would like to step down and have our documentation staff take care of the YAML file, including coming up with the correct OMA-URI. I mean, I can detect the "_Enum" case, if the URI needs that suffix, but I am still confused how the implementation can link that URI to the policy or registry key, which do not have that suffix. I am totally lost about the P_ prefix.

[mkaply]

I haven't forgotten about you. Just sidetracked. I'll respond later today.

[mkaply]

Where does the P_ prefix come from in your DisableSecurityBypass policy, which does not seem to be present in any of the GPO, PLIST and JSON entries?

It was done purely to fix alphabetization. Windows alphabetizes based on the name of policy in the ADMX, not the text, so we added those in quote a few places to make it alphabetize.

Or the _Enum suffix in the DisplayBookmarksToolbar policy?

That was done because we already had a DisplayBookmarksToolbar and I had to come up with a name for the new enum version of the policy.

Is there an algorithm to come up with the correct URI?

Yes.

./Device/Vendor/MSFT/Policy/Config/FirefoxPolicyfirefoxCATEGORY_ID/NAME
or if it is toplevel
./Device/Vendor/MSFT/Policy/Config/FirefoxPolicyfirefox/NAME
you can also have nested categories like:
./Device/Vendor/MSFT/Policy/Config/FirefoxPolicyfirefoxPermissions~Camera/Camera_Allow

Everything between the tildes is categories.

Are PLIST and JSON entries also at risk to have non-standard entries? If not, we could only specify the OMA-URI individually and have GPO, PLIST and JSON entries be generated from a common base config

No. It's really only the OMA-URIs that are weird because the rely on the ADMX. Everything else uses the information in the Schema directly.

But we would still be left with a knowledge deficit, because after finishing this generator project I would like to step down and have our documentation staff take care of the YAML file, including coming up with the correct OMA-URI. I mean, I can detect the "Enum" case, if the URI needs that suffix, but I am still confused how the implementation can link that URI to the policy or registry key, which do not have that suffix. I am totally lost about the P prefix.

The OMA-URI comes directly from the name= in the ADMX.

[mkaply]

FYI, this might become more important based on some work we are doing, so I might want to work more on it.

[jobisoft]

This is awesome news. Would you like to chat in a meeting?

[mkaply]

Definitely. I'll reach out via email.