Troubleshooting Policies. Amy Knox Staff Software Engineer, IBM Domino L2 Support team April 29, 2015

Transcription

1 Troubleshooting Policies Amy Knox Staff Software Engineer, IBM Domino L2 Support team April 29, 2015

2 Troubleshooting Policies - Agenda Helpful Vocabulary Policy Flow between Notes client and Domino server General Policy Flow (All except Mail Policies) Mail/Traveler Policies Domino Policy Gotchas and Best Practices Troubleshooting Information to Gather Troubleshooting Tools Testing Policies Additional Resources Q&A 2 2

3 Troubleshooting Policies Helpful Vocabulary Policy Settings = Domino document that determines which features and options to enable/disable/manage/maintain for users Policy document = Responsible for assigning the policies to users. Contains a list of relevant settings docs to be applied to groups or users. Domino Directory = NAB = Directory = names.nsf on the Domino server; where policy and settings documents are created and stored PNAB = personal (local) user names.nsf; policy info is pushed to Notes clients and stored in the local ($Policies) view DCC = aka DynConfig is the Dynamic Client Configuration task; local Notes client task that polls for server-side policy updates HTA = the 'How to Apply' value for a particular policy setting; i.e. 'Set initial value', 'Set value whenever modified', 'Set value and prevent changes' Admin client = Domino Administrator client Designer client = Domino Designer client 3 3

4 Troubleshooting Policies: Policy Flow 4 4

5 Troubleshooting Policies Policy Flow 1. Read dyninfo from directoryprofile - <username> in the PNAB 2. Access home/mail* server. Client/user newly** authenticates with the home/mail server *Home/mail server must be in canonical format, and client location should match Person doc **First session after last login. 3. During authentication, policies are examined for updates 4. Policy information fetched from Directory 5. If change is detected, dynconfig update flag is returned 6. Store returned dynconfig info in PNAB in directoryprofile - <username> 7. Launch dynconfig and pass in the flags 8. Fetch policy types list from $PolicyProfile - <username> in PNAB 9. For each policy type, request the effective policy for that type for the server. 10.If not in policy cache, calculate effective policy using info from the Domino Directory. Then, store in cache. 11.Return effective policy to client 5 5

6 Troubleshooting Policies Policy Flow 12.Store policy in $Policies in PNAB 13.If archive policy has Archive Criteria documents referenced, fetch them and store them in PNAB. 14.After all policies are processed, notify Java side of the client. 15.Fetch How To Apply information from policyhta - <username> in PNAB 16.Fetch policy settings locally from PNAB, HTA settings are applied 17.Store settings as managed settings (Eclipse feature) 18.Dynconfig terminates, displays message in status bar: Additional Notes: Java client fetches local policy settings from the 'managed settings' C/C++ client fetches local policy settings from local PNAB You may see the message in step 18 twice, because DynConfig may run twice: once after client is started to apply updates locally from last policy sync; again after connecting to home server and an update is needed 6 6

7 Personal NAB: Effective Policies in $Policies view $PolicyProfile - <username> : settings info policyhta - <username> : How To Apply info directoryprofile -<username>: Dynconfig info & Managed Settings Policy Engine 9 17 Personal NAB Java (notes2) ServerThread dynconfig General Policy Flow Policy cache Directory Adminp C\C++(nlnotes) Standard Client Mail File Domino Server Policy Synopsis (polcysyn.nsf) Domino Directory: Policies Settings Archive Criteria Extended Settings definition Mail file: Calendar profile Mail settings Admin Client 7

8 Personal NAB: Effective Policies in $Policies view $PolicyProfile - <username> : settings info policyhta - <username> : How To Apply info directoryprofile -<username>: Dynconfig info Policy cache Policy Eng. Managed Settings ServerThread 1 Mail and Traveler Policies Directory Java (notes2) AdminP dynconfig 2 Personal NAB Mail File C\C++(nlnotes) Domino Server Standard Client Policy Synopsis (polcysyn.nsf) Domino Directory: Policies Settings Archive Criteria Extended Settings definition Mail file: Calendar profile Mail settings 1. Every 12 hours, adminp calculates the effective mail Admin Client policy for the local mail users. Mail has it's own version of HTA ( How To Apply ) settings 2. Stores it in the Calendar profile of the mail file. 8

9 Troubleshooting Policies: Gotchas and Best Practices 9 9

10 Troubleshooting Policies Gotchas and Best Practices Gotchas: Accessing the home/mail server on the client implies the home/mail server specified in the location doc, not the person doc. If the user connects to a server other than the home mail server in the current location document, the flow listed on the previous slides will NOT occur. The server gets the users' home/mail server from the Person doc Home/mail server MUST be in canonical format (not IP Address) in the field properties Mail Policies are processed by Adminp every 12 hours, by default Use tell adminp process mail policy (tell adminp p ma) to force immediately Use the notes.ini parameter ADMINP_POLL_INTERVAL=<time_in_minutes> to change default Mail Preferences data comes from the calendar profile, not the ($Policies) in PNAB. Like all profile doc data, this is sticky for the duration of that client session. Switching domains via Location document also switches policies Some Policy Settings get pushed to the client during the first/next authentication, then take effect or display after the second/following one (i.e. some Security or Mail settings) 10 10

11 Troubleshooting Policies Gotchas and Best Practices More Gotchas: Policy management requires specific ACL privileges in the Domino Directory PolicyCreator, PolicyModifier; (UserCreator/UserModifier if registering users or setting via person doc) Policies require valid signatures and a valid user.id to save/sign the policy docs: To verify: Look at the $Signature field on the doc. It should match the $UpdatedBy field value. Don't rely on the Signed By column in the Policy view Open the policy doc and look for the Signature/Encryption icon. To resign policy docs: Re-save OR use Actions --> 'Resign policy' in the Policy view Policies are UNID dependent: Settings docs are linked to policy docs via UNID: Thus: Copying/Pasting policy and settings docs (including archive criteria) from one Domino Directory to another doesn't automatically make them all work! After copying, you must re-link policy and settings docs: Re-choose settings from drop-down list Look at the fields <Type>Sets: *EX: ArcSets, MailSets, TravelerSets, SecSets, etc

12 Troubleshooting Policies Gotchas and Best Practices More gotchas: Dynamic vs. Explicit Policies: Dynamic uses the 'Explicit' policy Form Dynamic = set via policy doc Policy Assignment tab (*Preferred method) Explicit = set via Person doc; Exception policy: Caveat = harder to maintain Easy to forget about! Overrides and ignores other policy docs set via inheritance Set in either explicit or organizational policy docs Administration tab: 12 12

13 Troubleshooting Policies Gotchas and Best Practices More Gotchas Precedence, Inheritance, Enforcement, HTA 3 Policy types: Organizational Dynamic Explicit > Increasing Precedence < Increasing Scope Precedence applies to Dynamic policies; 3 main ways to view precedence: Any docs created with the Explicit policy form Policy/Precedence tab Policies\Dynamic Policies view of Domino Directory *Explicit policies have precedence over Dynamic; Dynamic have precedence over Org policies Admin Client: People and groups tab; Under Policies Dynamic Policies (including 'By category' view) Precedence can be changed in Dynamic Policies views: Increase/Decrease buttons Not all precedence lists start with a 1 - evidence of doc deletion; Default field value = 1 Precedence determines which settings are set + their values. HTA determines the persistence of those settings over time. Enforce options override precedence; Inheritance compliments precedence NOT the same thing as locked down (HTA Set value and prevent changes ) 13 13

14 Troubleshooting Policies Gotchas and Best Practices Summary of Inheritance/Precedence/Inheritance/Enforce/HTA Options: Field values, values HTA, HTA Inheritance, Inheritance and Enforce options are set in settings docs Dropdown menu for HTA indicates a UI option that can be viewed/edited (Exception: Archive Settings for Archive Profile: Archive Options Dialog box pulls Archive Profile data) Policy Exception set in either Org or explicit type policy doc Current Precedence available within explicit type policy docs Dynamic policy views 14 14

15 Troubleshooting Policies Gotchas and Best Practices More Gotchas HTA (How to apply) values: *In general, if there is a UI display option for a particular setting, you will see the drop-down list in the Settings doc (Exception archive settings) Don't Set value - available for all options Does NOT mean use a default option; rather, it means the value does not exist for this policy Explicitly set any setting you don't intend to use to 'Don't Set value'. Set Initial Value Best used for initial deployments Can never be changed to a different value, if you modify the same policy at a later time* Old Setup policy = Desktop policy with Set Initial for all values Set Value Whenever Modified Most commonly used (preferred) Set and Prevent Changes Use to lock down user modifiable settings Adds the field names of options set this way to $DPLocked field of the local and server Settings docs 15 15

16 Troubleshooting Policies Gotchas and Best Practices Best Practices: Limit the number of policies being used for ease of maintenance When possible: try to re-use settings docs for multiple policies Don't create different policies for each hierarchy of the domain Leverage precedence, inheritance, and enforce controls Modify policy and settings docs on the Administration server of the domain Leverage auto-populated groups (8.5x and above) Details here Leverage 'Machine-specific' options when appropriate and available Example: Desktop policy Mail tab Local Mail file field set to Create Managed Replica As often as possible: Use dynamic policies with groups, not individual users Be aware of which options are set to Set initial value - Use only for setup situations. For best results, Don't delete policies and settings docs form the Domino Directory. First, change them to default values and deploy as such. Then Disable the policy: Explicit: clear entries in the Policy assignment tab Organizational: modify the fullname of the policy 16 16

17 Troubleshooting Policies Gotchas and Best Practices More Best Practices: Remember the gotchas about copying/pasting/deleting policies Remember to explicitly set any setting you don't intend to use to 'Don't Set value' Consider a particular Policy Signer ID file, vs. an individual or admin user.id. Benefit: If the admin or individual leaves, you still have valid signer id for all policies no need to resign. This prevents the error Policy has been modified since signed when that user/signer leaves Caveat: Harder to know exactly who last modified the policy Consider using a small test group when Testing policies test an explicit policy first When testing multiple id files from the same machine, create a unique location doc for each user.id Location doc Advanced Basics: User id to switch to field Ensure the correct home/mail server is set in MailServer field Resave user Person doc after each policy or settings doc change, in addition to re-saving policy and settings doc(s) you are testing 17 17

18 Troubleshooting Policies: Information to Gather 18 18

19 Troubleshooting Policies Information to Gather 1. What type of policy are we troubleshooting: organizational, dynamic, explicit? 2. How are policies applied: via groups or individual? Via person doc or policy doc? 3. Are all users affected, just some, or only one? Get details about affected users, i.e. are they in the same groups? Same domain? 4. Is the policy applied to the user(s) at the server-level (policy synopsis)? 5. Which settings docs (type and name) are we troubleshooting in the relevant policy? 6. Does the policy make it to the user's Notes client (relevant profile doc - inotes/traveler)? 7. If the policy does make it to the client, are all the policy settings getting pushed down? 8. Which piece(s) of the policy deployment are not working as expected? a.) are some of the settings (docs) getting applied, but not others? b.) are some of the options within those settings are getting applied, but not others? c.) is the how to apply option working/not working for the relevant setting(s)? d.) Are the correct policy setting values getting pushed down, or are they incorrect? 19 19

20 Troubleshooting Policies Information to Gather 9. Is the user authenticating with their home/mail server (user/server log.nsf)? 10. Is the DCC task running on the Notes client (check the user log.nsf)? 11. Is this a new or existing policy/settings doc? 12. Is this a new user or existing user? Cloud vs. OnPrem user? 13. Has this ever worked before? 14. Is the end user Notes client Basic or Standard (affects Managed Settings )? 15. If dynamic policy and assigned to groups, and some users may not be getting policy updates, changes, or new assignments, is the group cache full (rare case)? Show stat NET.* Increase group cache using GROUP_CACHE_SIZE=<sizeInKb> 20 20

21 Troubleshooting Policies: Troubleshooting Tools 21 21

22 Troubleshooting Policies Troubleshooting Tools 1. Policy synopsis Tool Verify the policy/settings applied to user(s) 2. Domino Directory a.) UI of the policy and settings docs b.) ($PoliciesByGroup) view 3. Domino Designer client for verifying field names of respective settings 4. NotesPeek for verifying fields/values in respective db profile docs. 5. Local Notes client names.nsf: a.) ($Policies) view for reviewing local policy docs, field values b.) ($Programs) view for reviewing locally scheduled programs (i.e. archive) c.) Locations view for verifying location doc data and home/mail server 6. Local user Notes client log.nsf a.) Miscellaneous events displays the DCC b.) Security events stores relevant security policy info (i.e. ID Vault status and errors) 7. Admin client log.nsf messages or errors (i.e. during registration) *NOTE: Field names in policy synopsis = field names on the Form, server policy docs and local policy docs 8. Debug and notes.ini parameters 22 22

23 Troubleshooting Policies Troubleshooting Tools 1. Policy Synopsis tool: Where to find it: Domino Administrator Client People and Groups tab (Or Configuration tab) a.) Tools Menu Far right b.) Right-click menu 23 23

24 Troubleshooting Policies Troubleshooting Tools 1. Policy Synopsis tool: How to execute it: a.) Select/Highlight the user in the list. Either Right-click to expose the right-click menu OR select the Policy Synopsis tool from the tools menu b.) Select either Summary or Detailed Report type Use Summary for general policy doc information Use Detailed for field by field report of the Settings docs you select and wish to diagnose c.) Choose the results db (Default = Local polcysyn.nsf) And how to report (Default = append) End Result: Policy synopsis database opens, and a new doc appears at the bottom of the view. If a new doc with <Now> timestamp does not appear, refresh the view. Open this doc to display either the Policy summary OR the Detailed list of fields for each settings docs you selected

25 Troubleshooting Policies Troubleshooting Tools 1. Policy Synopsis tool: End Result Detailed Report: 25 25

26 Troubleshooting Policies Troubleshooting Tools 2. Domino Directory: Policy/Settings docs and Doc Properties Fields tab: Right-click on a doc in the view OR with doc open Document Properties Second tab = Fields tab Left = Field name Right = Field value *Note: There are different number of fields listed with doc opened vs closed... Usage: Compare field names/values: a.) Policy synopsis doc b.) Policy/settings docs of Domino Directory --UI of the documents --Doc properties Fields tab c.) Policy form (Designer client) d.) Local policy doc ($Policies) 26 26

27 Troubleshooting Policies Troubleshooting Tools 2. Domino Directory: ($PoliciesByGroup) view: Helpful when troubleshooting group assignments: 27 27

28 Troubleshooting Policies Troubleshooting Tools 3. Domino Designer client names.nsf Policy/Settings forms a.) Open server names.nsf. View Design. This launches Designer, to the list of Forms b.) Find the Policy or Settings form you wish to review, dbl-click to open c.) Find the fields you are investigating, on the form, note the field names and choices. The field location should match up with the UI display. Choices available in 2 nd tab of field properties. Steps a.) and b.) 28 28

29 Troubleshooting Policies Troubleshooting Tools 3. Domino Designer client names.nsf Policy/Settings form (Step c.) 29 29

30 Troubleshooting Policies Troubleshooting Tools 3. Domino Designer client names.nsf Policy/Settings forms (Step c.) Right-click on the field Field Properties Designer client Field Properties showing available options: In this example, there are 2 options, 1 and 2. In the policy settings doc, we saw the field value of 1, or User's local workstation. Thus, archiving should be executed locally

31 Troubleshooting Policies Troubleshooting Tools 3. Domino Designer client names.nsf Policy/Settings forms (Step c.) Notes client/admin client view: Designer view: 31 31

32 Troubleshooting Policies Troubleshooting Tools 4. NotesPeek: Free downloadable tool found here Usage: View Field names and values in relevant Profile documents or databases Mail Settings: Calendar Profile inotes Mail Settings: Calendar profile, inotes profile, etc. Archive Settings: mail file Archive Profile NOTES: To use local NotesPeek exe on active server mail dbs, you will either need to shut down the Domino server OR you can pull a local replica of the db and use NotesPeek locally without issue. *Some options get set in different field names in profile docs or preferences: Example: ArcLoc value gets stored in ArchiveOnClientOrServer field: 1 for client based archiving 2 for server based archiving 32 32

33 Troubleshooting Policies Troubleshooting Tools 5. Local Notes client names.nsf: Using the ($Policies) view: a.) Open the ($Policies) view of the local names.nsf Any view enclosed in () is designated as a Hidden view Two ways to access hidden views in any database: Hold down the Ctrl+Shift keys of the keyboard, then open the database With db already open, hold down the ctrl+shift keys, View Go To; Select Desired view, and click OK to open: 33 33

34 Troubleshooting Policies Troubleshooting Tools 5. Local Notes client names.nsf: Using the ($Policies) view: b.) Locate the policy or settings document you wish to review. Looking at first column: Effective Policy for <username> designates the policy document Policy<Type> (i.e. PolicyArchive, PolicyMail, PolicySecurity, etc.) designates Settings docs c.) Right-click on the document Document Properties, to review field names/values *REASON: Local names.nsf does not have policy or settings forms; Error Cannot locate form:<name> 34 34

35 Troubleshooting Policies Troubleshooting Tools 5. Local Notes client names.nsf: ($Policies) view: Other helpful fields for Initial debugging: In the local Policy doc: $DPLocked: same as server, contains a list of locked features/options $PoliciesList: Contains a list of applied policies, according to the Notes client $FL_n fields: Refer to the HTA values for MAIL policy docs: $FL_1 = Don't set value $FL_2 = Set value whenever modified and Set value and prevent changes $FL_3 = Set initial value 35 35

36 Troubleshooting Policies Troubleshooting Tools 6. and 7. Local Notes client log.nsf/admin client log.nsf: Open docs that fit time stamp of next authentication after policy changes: a.) Miscellaneous Events view b.) Security Events view 36 36

37 Troubleshooting Policies Troubleshooting Tools 8. Notes.ini and Debug Parameters: Parameter: Possible Values*: Where to use: Debug_Policy= 1 = normal; 2 = verbose; 4 = very verbose 7 = all Notes client, Domino server Debug_Dynconfig= 1 Notes client, Domino server Debug_Policy_Create= 1 Admin client Debug_Policy_Synopsis= 1 Admin client Console_Log_Enabled= (Debug_ThreadID= 1 (0 = off) (1/0) Notes client, Admin client, *Domino server (*Enabled by default Domino server_ DEBUG_DUMP_POLICY= 1 Domino server DEBUG_POLICY_SIGNBIT= 1 Domino server *In all cases, 0 = disabled 37 37

38 Troubleshooting Policies Troubleshooting Tools Debug parameters For Initial/General Troubleshooting: For affected Notes client(s) For the Admin client (*For debugging issues creating policies or with policy synopsis tool) Debug_Policy=1 Debug_Dynconfig=1 Debug_ThreadID=1 Console_log_enabled=1 Debug_Policy_Create=1 Debug_Policy_Synopsis=1 Debug_ThreadID=1 Console_log_enabled=1 For the Domino server: Debug_Policy=1 *(Debug_ThreadID=1) *(Console_log_enabled=1) *Enabled by default, If this does not produce helpful info: Debug_Policy=7 (client or server) this dumps the whole policy! Debug_Dynconfig=1 (server) this will show the client DCC connection info 38 38

39 Troubleshooting Policies: Testing Policies 39 39

40 Troubleshooting Policies - Testing Policies When testing policies, these are good steps to execute: *Note: I tend to work with dynamic or explicit policies first, and with test users whose home/mail server = admin/hub server 1. Create test users. 2. Create/Edit/Resave the settings doc 3. Create/Edit/Resave the policy doc *Assign the dynamic policy to the user or group (for starters, preferably one who has never received any policies before.) 4. Trigger the policy to apply to user(s): a.) Edit/Resave the user's person doc OR b.) 'Load updall names.nsf -T $Policies -R' OR c.) Change group assignments (or re-save existing group doc), if testing groups 5. (If applicable) Replicate HUB names.nsf with user(s) home/mail server. *Pushes policy, person, and group membership changes to home/mail server 6. Run policy synopsis on home/mail server Ensure the policy/settings applied to the user as expected

41 Troubleshooting Policies - Testing Policies Good testing steps, continued: 7. (For mail policies only): On Home/mail server, wait at least 1 minute. Execute the command tell adminp process mail policy on user's home/mail server. 8. Shut down the Notes client of the id file you are testing. 9. Shut down and relaunch admin client; switch id to the test user you are testing and authenticate with the home/mail server (open any db). 10. Check the local names.nsf ($Policies) view. a.) Did the policy doc get pushed? b.) Do you see 2 docs in the view that represent each policy type? c.) Do the field values in the docs match the server policy and settings docs? d.) Look at the timestamp of the policy doc: Is it recent or old? 11. Check the local log.nsf, Miscellaneous Events view did DCC task run? If Security policy, check Security Events view, current time, for messages/errors. 12. (If applicable) Use NotesPeek to verify Mail settings in the mail database. 13. Shut down the client again. Re-launch, and re-authenticate with home/mail server

42 Troubleshooting Policies - Testing Policies If you do not have the desired results yet: 13. Create and test a new settings and new policy doc different type. 14. Isolate one type of settings docs at a time (i.e just mail, just security, etc.), and try rolling out only a small number of options. Use Set value whenever modified if possible. 15. If you have not yet done so, restart the Domino server. 16. Test a single-server setup eliminates any replication/adminp issues on mail server (i.e. a user whose home/mail server = HUB/Admin server) 17. Ensure client authenticates with home/mail server after any/every policy change. 18. On the Notes client, Run dynconfig manually from the Notes program directory: *Command: ndyncfg.exe

43 Troubleshooting Policies - Testing Policies If you do not have the desired results yet (continued): 19. Test a new client setup: Clear notes.ini of all except first 5 lines, re-launch the client. 20. Repeat step 19, this time with a new local names.nsf. 21. Test a NEW Notes client install, new names.nsf, new everything for the user. *NOTE: Starting with version 8.5.1, it is no longer OK to remove policy docs from ($Policies) view this previous troubleshooting step will not work! 22. Implement debug parameters, collect output, and open a PMR with IBM Support: Notes client console.log (containing debug output) Notes client log.nsf Notes client PNAB console.log from Domino server (containing any relevant debug output) Replica or OS Copy of Domino Directory containing at least: Policy and settings docs User Person doc(s) (Helpful but not essential) Domino server and Notes client notes.ini 43 43

44 Troubleshooting Policies: Additional Resources 44 44

45 Troubleshooting Policies - Resources Notes / Domino Policy Troubleshooting Flow Chart Domino Policy Precedence Explained Domino Policies - How To Apply feature explained Troubleshooting difficulties with applying policies in Notes/Domino Self-Training: Troubleshooting Domino policies and settings documents Troubleshooting Policies on a Domino Server (Open Mic 2012) Ask the Experts Q&A session: Managing Domino Policies (May 2014) NotesPeek technote and tool 45 45

46 Questions? Press *1 on your telephone to ask a question. Visit our Support Technical Exchange page or our Facebook page for details on future events. To help shape the future of IBM software, take this quality survey and share your opinion of IBM software used within your organization: IBM Collaboration Solutions Support page IBM Collaboration Solutions Support