Articles September 27, 2004 at 9:35 am

Using pwpolicy to Manage User Password Policies via CLI

Have you ever wanted or needed to change a user’s password policies from the command line? Read on to find out how pwpolicy can help you manage user’s passwords without Workgroup Manager.If I had to pick just one nit to pick with Apple it would be the seemingly accidental secrecy that many of their products exist in. From the old ColorSync displays to the CLI bits of Mac OS X Server Apple seems to not care about letting people know about the cool stuff that they have. pwpolicy, like many Mac OS X Server components is a good example of this. It can be a very useful tool, but it gets a grand total of two sentences in the Command Line Administration manual. And the two lines that it gets is just to tell you to read the man page!

As I said earlier, pwpolicy is the CLI tool for adjusting the password policies of your Password Server users. (As of 10.3.4 or so you can also use pwpolicy on the client on non-PWS users as well but it’s functionality seems to be limited.) Let’s say for example that I wanted to do something as simple as change a user’s password:

pwpolicy -a pws_admin -u usertochange -setpassword newpassword

Or you can do more complicated things. Let’s say I want to set a global policy that says passwords must be a minimum of 6 characters, a user can’t use a password that they have used in the previous 4 passwords, it must contain at least one number, and it must be changed every 30 days:

pwpolicy -a pws_admin -setglobalpolicy "minChars=6 usingHistory=4 requiresNumeric=1 maxMinutesUntilChangePassword=43200"
(Command is all one line of course…)

If I wanted to see what the global policies are set to I would use:

pwpolicy -getglobalpolicy

Some settings are by user, not global. These include:

  • isDisabled
  • isAdminUser
  • newPasswordRequired
  • canModifyPasswordforSelf
  • Now you might be wondering why the heck you should care about using pwpolicy since Workgroup Manger can set all of these settings, and it can even do them with bulk edits. That’s a good point, but what if you can’t get to a Workgroup Manager session? I can use pwpolicy via an ssh session from a Windows box if need be, and there is one more great use for pwpolicy; automation.

    Say you are using Joel’s spiffy OD adduser script but you want the users to be created with a default password and set the password policy to force a change on first login. You could just add a:

    pwpolicy -a pws_admin -p pws_admin_password -u usertochange -setpolicy"newPasswordRequired=1"
    (All one line of course and make sure to keep this script secure since it now has a password in it.)

    to the end of the adduser script.

    Here is another useful tip: Mac OS X Server dosen’t have a “login hours” type setting that can restrict the times a user can use a workstation. We can fake that setting with pwpolicy and cron.

    First we need two simple shell scripts. One to disable the accounts and a second to enable them.


    pwpolicy -a pws_admin -p pws_admin_password -u usertochange -setpolicy"isDisabled=1"
    sleep 5
    pwpolicy -a pws_admin -p pws_admin_password -u anotherusertochange -setpolicy"isDisabled=1"
    sleep 5
    exit 0

    The second script is the same except that “isDisabled=0” is the command. Then you just need to schedule the first one to run when you want to lock the users out and the re-enabling script when you want to let them back in. Note that this won’t force a logout on an active session, but it will stop any authentication attempts for that account until it is re-enabled.

    As always, take a look a the pwpolicy man page for more info. I need to mention though that the current man page isn’t up to date with the current binary. The only difference is that the man page lacks the -convertdate option which will convert a human readable date (mm/dd/yy) into a GMT long number that can be used by the expirationDateGMT or hardExpireDateGMT policies.

    Have fun!

    No Comments

    • I have done some testing of pwpolicy under OS X client.

      I am using pwpolicy to enforce password length and complexity on NISPOM
      classified systems.

      As “macshome” states pwpolicy is limited under OS X client. However, it is
      still useful.

      These are the global policies that I have tested and work correctly.

      Here is a good example of a global password policy for OS X client.
      pwpolicy -n /NetInfo/DefaultLocalNode -a admin -setglobalpolicy
      minChars=8 requiresNumeric=1 requiresAlpha=1

      Here it is the command broken down and explained.

      pwpolicy -n /NetInfo/DefaultLocalNode
      This specifies you are working in the local Netinfo Database. There is no
      password server in OS X client. I had trouble with the pwpolicy command until
      I realized I had to specify /NetInfo/DefaultLocalNode.

      -a admin
      You must specify a local admin account to authenticate with. Root will not

      -setglobalpolicy minChars=8 requiresNumeric=1 requiresAlpha=1

      These policies affect all the users. The next time an existing user changes
      their password they will be forced to comply.

      It is possible to create a new user with a bad password but they will be forced
      to comply the next time they change their password. Ideally they will
      change it right away.

      Another exception is admin users do not get locked out after X failed login

      So make sure to assign an initial strong password. Have the user change the
      password right away. And be careful whom you make an admin user.

      Some of the global policies do not work in the local NetInfo database with OS
      X client.
      If you set this above 0
      your non admin users will not be able to log in. Even after changing it back
      the non admin users will still be disabled.

      This has the same

      If one of your non admin users gets disabled you have to use /Applications/
      Utilities/NetInfo Manager to reactivate them.
      In the authentication_authority property remove the value ;

      The Additional User Policies don’t seem to apply to the local NetInfo database


      • Hey! Thanks for the detective work on using pwpolicy on a
        Mac OS X client.

        Breaking my server to save yours.

        Josh Wisenbaker

      • Admin users are not bound by any of pwpolicy’s options. Nor are they
        affected by it on OS X Server. This is expressly to prevent an admins from
        locking themselves out of their machines.

        Changing the world, one server at a time.

        Joel Rennich

      • One small edit to this post.

        You need to use quotes "" around the globalpolicies.

        Here is a good example of a global password policy for OS X client.
        pwpolicy -n /NetInfo/DefaultLocalNode -a admin -setglobalpolicy
        "minChars=8 requiresNumeric=1 requiresAlpha=1

      • However, if you updated a workstation from 10.2, your admin account might
        show :basic: authentication in Netinfo Manager. If so, then it will not work for
        pwpolicy until you change the password at least once, which will then make it
        show :shadow_hash:. Eric and I learned this the hard way…

      • If you have not setup a policy and you try to getglobalpolicy you get the error you mentioned.

        try setting some policies.

        pwpolicy -n /NetInfo/DefaultLocalNode -a admin -setglobalpolicy "minChars=8 requiresNumeric=1 requiresAlpha=1"

        Then you can look at all the policies.

        pwpolicy -n /NetInfo/DefaultLocalNode -a admin -getglobalpolicy

      • Here is one thing that got better with Tiger.
        All the pwpolicy settings seem to work under Tiger now.

    • I want to Create/Delete, modify a Share through CLI. Is there any CLI utility available so that i can use such commands through my application to create Share.
      I am using MAC OS 10.3.

      Please Help me


    • This article was written back in the Panther days and it should work. A comment
      post further up the page shows the policies that work on Panther client.

      Breaking my server to save yours.

      Josh Wisenbaker

    Leave a reply

    You must be logged in to post a comment.