Mac Developer Library Developer


This manual page is for Mac OS X version 10.9

If you are running a different version of Mac OS X, view the documentation locally:

  • In Terminal, using the man(1) command

Reading manual pages

Manual pages are intended as a quick reference for people who already understand a technology.

  • To learn how the manual is organized or to learn about command syntax, read the manual page for manpages(5).

  • For more information about this technology, look for other documentation in the Apple Developer Library.

  • For general information about writing shell scripts, read Shell Scripting Primer.

asctl(1)                  BSD General Commands Manual                 asctl(1)

     asctl -- App Sandbox Control Tool

     asctl [-p] [--container-path <path>] command [arguments]

     Many commands require an application specification as one of their arguments.  Applications can be
     specified any of the following ways:

     <name>  The application name as it appears in the Applications folder, with or without the .app exten-sion. extension.
             sion.  For example, "TextEdit".

     <path>  The path to the application binary or bundle.  For example, "/Applications/".

     --file <path>
             Explicitly indicate the following argument is to be interpreted as the path to the application
             binary or bundle.  The --file flag removes ambiguity when an argument can be interpreted as
             either an application name or a valid path to an application.  For example, "--file /Applica-tions/". /Applications/".

     --bundle <bundle Id>
             Interpret the following argument as the bunder identifier of the application.  For example,

     --pid <process Id>
             Interpret the following argument as the process identifier of a running application.  For exam-ple, example,
             ple, "--pid 1".

     help    Prints a summary of commands and their behaviours.

     sandbox check <app specification>
             Determines with the given application is signed with App Sandbox entitlements.  In addition, if
             the application is specified by pid using the --pid syntax, prints out whether the application
             is actually running with App Sandbox enabled, a traditional sandbox, or no sandbox at all.

     The following commands manage filesystem containers for sandboxed apps.

     container path <app specification>
             Print the path to the application's container.

     container create <app specification>
             Create and initialize the application's container.  Containers are normally created automati-cally automatically
             cally when sandboxed applications are run.  This command creates the container for an applica-tion application
             tion without running the application.

     container upgrade <app specification>
             Upgrade the application's container to the current container schema.  Existing containers are
             normally automatically upgraded to the latest container schema when their associated applica-tions applications
             tions are run.  This command upgrades an existing container without running the associated

     Each container has an access control list comprised of code requirements.  A sandboxed application must
     satify one or more of the code requirements on their container in order to run.

     The following commands manipulate the container's access control list:

     container acl add <app specification>
              Update the access control list for the application's container to include the application's
              designated code requirement.

     container acl add <app specification> <code requirement>
              Update the access control list for the application's container to include the specified code

     container acl update <app specification>
              Update the access control list for the application's container such that it consists of only
              the application's designated code requirement.  Any other code requirements will be removed
              from the ACL.

     container acl list <app specification>
              Print list of code requirements in the access control list for the given application's con-tainer. container.

     container acl validate <app specification>
              Validate the application against each of the code requirements in its container's access con-trol control
              trol list.  Each code requirement in the ACL is labeled with one of the following:

              [FAIL]   application does not validate against code requirement.

              [VALID]  application validates against code requirement.

              [EXACT]  application validates against code requirement and code requirement is the same as
                       the application's designated code requirement.

     container acl verify <app specification>
              Synonym for acl validate.

     App Sandbox will follow any symlinks in the paths to users' home directories.  In addition, it has a
     whitelist of other locations where it will acknowledge and honor symbolic links.  Any symlinks not in
     this whitelist will not be followed and, as a result, App Sandboxed applications will not have access
     to the paths that the symlinks refer to.

     The following command displays the whitelist of paths where App Sandbox will acknowledge symlinks at:

     symlink list <path ...>
              Display the list of paths that App Sandbox searches for symlinks and, for any paths that are
              symlinks, display where the symlinks currently resolve to.

     Collect diagnostic information related to Application Sandboxing and containers.  The information is
     collected into a single file that can be sent to Apple to aid in diagnosing problems when an applica-tion application
     tion runs inside of a sandbox.  Should you choose to send the diagnostic information to Apple, then you
     must agree to this disclaimer:

     This diagnostic tool generates files that allow Apple to investigate issues with your computer and help
     Apple to improve its products. The generated files may contain some of your personal information, which
     may include, but not be limited to, the serial number or similar unique number for  your  device,  your
     user  name,  your file names or your computer name. The information is used by Apple in accordance with
     its privacy policy ( and is not shared with any third party.   By  enabling  this
     diagnostic  tool  and sending a copy of the generated files to Apple, you are consenting to Apple's use
     of the content of such files.

     Additional information concerning a specific application can be gathered via the app subcommand.  This
     command must be run as 'root'.

     The following command collects diagnostic information:

     diagnose [--no-compress | --no-disclaimer | --no-reveal | --no-verbose] [app <app specification>]
              Collection diagnostic information. Outputs the path to the folder or file containing the
              Optional arguments:

                       Do not compress the folder containing the dianostic files into a Zip file.

                       Do not show the disclaimer. Use of this option constitutes acceptance of the dis-claimer. disclaimer.

                       Do not reveal the resulting diagnostic file in Finder.

                       Do not show verbose output while running the diagnostic.

              Optional subcommand:

              app <app specification>
                       Specify an application for which additional information will be gathered.

     -p       By default, asctl displays paths relative to the user's home directory.  This flag causes any
              paths in the output to be displayed as absolute paths instead.


     The asctl command first appeared in Mac OS X Version 10.7.

BSD                            February 7, 2012                            BSD

Reporting Problems

The way to report a problem with this manual page depends on the type of problem:

Content errors
Report errors in the content of this documentation with the feedback links below.
Bug reports
Report bugs in the functionality of the described tool or API through Bug Reporter.
Formatting problems
Report formatting mistakes in the online version of these pages with the feedback links below.