BITSAdmin Tool (Windows)

BITSAdmin is a command-line tool that you can use to create download or upload jobs and monitor their progress.

The \Support\Tools\Support.cab file on the operating system installation CD contains the BITSAdmin tool. To unpack and install BITSAdmin, run the Setup. exe file in the Tools directory. If you do not have access to the installation CD, you can download the support tools from Windows XP Service Pack 2 Support Tools.

The BITSAdmin tool uses switches to identify the work to perform. Most switches require a Job parameter that you set to the job's display name or GUID. Note that a job's display name may not be unique. The /create and /list switches return a job's GUID.

By default, you can access information about your own jobs. To access information for another user's jobs, you must have administrator privileges. If the job was created in an elevated state, you must run BitsAdmin from an elevated window; otherwise, you will have read-only access to the job.

Many of the switches correspond to methods in the BITS interfaces. For additional details that may be relevant to using a switch, see the corresponding method.

Use the following switches to create a job, set and retrieve the properties of a job, and monitor the status of a job. For examples that show how to use some of these switches to perform tasks, see BITSAdmin Examples.

/AddFile Job RemoteURL LocalName

Adds a file to the specified job. RemoteURL is the URL of the file on the server. LocalName is the name of the file on the local computer. LocalName must contain an absolute path to the file.

/AddFileSet Job TextFile

Adds one or more files to the specified job. Each line in TextFile contains a remote and local file name. The names are space-delimited. Lines that begin with a # character are treated as a comment.

/AddFileWithRanges Job RemoteURL LocalName RangeList

Adds a file to the specified job. BITS downloads the specified ranges from the remote file. Switch is valid only for download jobs. RemoteURL is the URL of the file on the server. LocalName is the name of the file on the local computer. LocalName must contain an absolute path to the file.

RangeList is a comma-delimited list of offset:length pairs. For example, the following range list tells BITS to transfer 100 bytes from offset 0, 100 bytes from offset 2000, and the remaining bytes from offset 5000 to the end of the file.

0:100,2000:100,5000:eof

/Cancel Job

Removes the job from the transfer queue and deletes all temporary files associated with the job.

/Complete Job

Completes the job. The downloaded files are not available to you until you use this switch. Use this switch after the job moves to the transferred state. Otherwise, only those files that have been successfully transferred are available.

/Create [/type] DisplayName

Creates a transfer job with the given DisplayName. You can specify /Download, /Upload, or /Upload-Reply for the type parameter. The default type is /Download.

Download jobs transfer data from a server to a local file. Upload jobs transfer data from a local file to a server. Upload-reply jobs transfer data from a local file to a server and receive a reply file from the server.

Use the /resume switch to activate the job in the transfer queue.

/GetAclFlags Job

Retrieves the ACL propagations flags. Displays one or more of the following flag values:

O — Copy owner information with file.
G — Copy group information with file.
D — Copy DACL information with file.
S — Copy SACL information with file.

/GetBytesTotal Job

Retrieves the size of the specified job.

/GetBytesTransferred Job

Retrieves the number of bytes transferred for the specified job.

/GetCompletionTime Job

Retrieves the time that the job finished transferring data.

/GetCreationTime Job

Retrieves the job creation time for the specified job.

/GetDescription Job

Retrieves the description of the specified job.

/GetDisplayName Job

Retrieves the display name of the specified job.

/GetError Job

Retrieves detailed error information for the specified job.

/GetErrorCount Job

Retrieves a count of the number of times the specified job generated a transient error.

/GetFilesTotal Job

Retrieves the number of files in the specified job.

/GetFilesTransferred Job

Retrieves the number of files transferred for the specified job.

/GetMinRetryDelay Job

Retrieves the length of time, in seconds, that the service waits after encountering a transient error before trying to transfer the file.

/GetModificationTime Job

Retrieves the last time the job was modified or data was successfully transferred.

/GetNoProgressTimeout Job

Retrieves the length of time, in seconds, that the service tries to transfer the file after a transient error occurs.

/GetNotifyCmdLine Job

Retrieves the command-line command to execute when the job finishes transferring data.

/GetNotifyFlags Job

Retrieves the notify flags for the specified job. The job can contain one or more of the following notification flags.

0x0001 — Generate an event when all files in the job have been transferred.
0x0002 — Generate an event when an error occurs.
0x0004 — Disable notifications.
0x0008 — Generate an event when the job is modified or transfer progress is made.

/GetNotifyInterface Job

Determines if the notify interface is registered for the specified job. Displays REGISTERED or UNREGISTERED.

/GetOwner Job

Retrieves the owner of the specified job.

/GetPriority Job

Retrieves the priority of the specified job. The priority is either FOREGROUND, HIGH, NORMAL, LOW, or UNKNOWN.

/GetProxyBypassList Job

Retrieves the proxy bypass list for the specified job. The bypass list contains the host names or IP addresses, or both, that are not to be routed through a proxy. The list can contain "<local>" to refer to all servers on the same LAN. The list is space-delimited.

/GetProxyList Job

Retrieves the proxy list for the specified job. The proxy list is the list of proxy servers to use. The list is comma-delimited.

/GetProxyUsage Job

Retrieves the proxy usage setting for the specified job. The possible values are:

PRECONFIG — Use the owner's Internet Explorer defaults.
NO_PROXY —Do not use a proxy server.
OVERRIDE — Use an explicit proxy list.

/GetReplyData Job

Retrieves the server's reply data in hexadecimal format. Valid only for upload-reply jobs.

/GetReplyFileName Job

Gets the path of the file that contains the server reply. Valid only for upload-reply jobs.

/GetReplyProgress Job

Retrieves the size and progress of the server reply. Valid only for upload-reply jobs.

/GetState Job

Retrieves the state of the specified job. The possible states are:

QUEUED — The job is waiting to run.
CONNECTING — BITS is contacting the server.
TRANSFERRING — BITS is transferring data.
SUSPENDED — The job is paused.
ERROR — A nonrecoverable error occurred; the transfer will not be retried.
TRANSIENT_ERROR — A recoverable error occurred; the transfer retries when the minimum retry delay expires.
ACKNOWLEDGED — The job was completed.
CANCELLED — The job was canceled.

/GetType Job

Retrieves the job type of the specified job. The type can be DOWNLOAD, UPLOAD, UPLOAD-REPLY, or UNKNOWN.

/Help | /?

Displays the command-line usage.

/Info Job [/verbose]

Displays summary information about the specified job. Use the /verbose parameter to provide detailed information about the job.

/List [/allusers] [/verbose]

Lists the transfer jobs owned by the current user. To list jobs for all users, include the /allusers parameter. You must have administrator privileges to use the /allusers parameter. Use the /verbose parameter to provide detailed information about jobs.

/ListFiles Job

Lists the files in the specified job.

/Monitor [/allusers] [/refresh Seconds]

Monitors jobs in the transfer queue that the current user owns. To monitor jobs for all users, include the /allusers parameter. You must have administrator privileges to use the allusers parameter. The /refresh parameter refreshes the data at an interval specified by Seconds. The default refresh period is every 5 seconds. To stop the refresh, enter CTRL+C.

/NoWrap

Does not wrap output to fit in a command window. By default, all switches, except the /Monitor switch, wrap the output. Specify before other switches.

/RawReturn

Returns data suitable for parsing. Strips new line characters and formatting from the output. Typically, you use this switch in conjunction with the /create and /get* switches to receive only the value. Specify before other switches.

/RemoveCredentials Job Target Scheme

Removes credentials from a job. Target can be either SERVER or PROXY. Scheme can be BASIC, DIGEST, NTLM, NEGOTIATE, or PASSPORT.

/ReplaceRemotePrefix Job OldPrefix NewPrefix

All files in the job whose remote URL begins with OldPrefix are changed to use NewPrefix.

/Reset /AllUsers

Cancels all jobs in the transfer queue that the current user owns. If you have administrator privileges, you can specify /AllUsers to cancel all jobs in the queue.

/Resume Job

Activates a new or suspended job in the transfer queue.

/SetAclFlags Job flags

Sets the ACL propagations flags for the job. The flags indicate that you want to maintain the owner and ACL information with the file being downloaded. Specify one or more of the following flags. For example, to maintain the owner and group with the file, set flags to OG.

O — Copy owner information with file.
G — Copy group information with file.
D — Copy DACL information with file.
S — Copy SACL information with file.

/SetCredentials Job Target Scheme UserName Password

Adds credentials to a job. Target can be either SERVER or PROXY. Scheme can be BASIC, DIGEST, NTLM, NEGOTIATE, or PASSPORT.

/SetDescription Job Description

Sets the description of the specified job.

/SetDisplayName Job DisplayName

Sets the DisplayName of the specified job.

/SetMinRetryDelay Job RetryDelay

Sets the minimum length of time, in seconds, that BITS waits after encountering a transient error before trying to transfer the file.

/SetNoProgressTimeout Job Time-out

Sets the length of time, in seconds, that BITS tries to transfer the file after the first transient error occurs.

/SetNotifyCmdLine Job Program_Name[Program_Parameters]

Specify a command-line program to execute when the job finishes transferring data or is in error. You can specify NULL for Program_Name and Program_Parameters. If Program_Name is NULL, Program_Parameters must be NULL.

The following examples show how to use this switch:

bitsadmin /SetNotifyCmdLine MyJob C:\Winnt\System32\Notepad.exe NULL

bitsadmin /SetNotifyCmdLine MyJob C:\Handler.exe "C:\Handler.exe parm1 parm2 parm3"

bitsadmin /SetNotifyCmdLine MyJob NULL NULL

/SetNotifyFlags Job NotifyFlags

Sets the event notification flags for the specified job. Specify one or more of the following notification flags. For example, to specify transferred and error events, set NotifyFlags to 0x0003.

0x0001 — Generate an event when all files in the job have been transferred.
0x0002 — Generate an event when an error occurs.
0x0004 — Disable notifications.
0x0008 — Generate an event when the job is modified or transfer progress is made.

/SetPriority Job Priority

Sets the priority of the specified job. The priority must be either FOREGROUND, HIGH, NORMAL, or LOW.

/SetProxySettings Job usage List Bypass

Sets the proxy settings for the specified job. The usage parameter can be one of the following values:

PRECONFIG — Use the owner's Internet Explorer defaults.
NO_PROXY — Do not use a proxy server.
OVERRIDE — Use an explicit proxy list and bypass list. A proxy and proxy bypass list must follow.

The List parameter contains a comma-delimited list of proxy servers to use. The Bypass parameter contains a space-delimited list of host names or IP addresses, or both, for which transfers are not to be routed through a proxy. This can be <local> to refer to all servers on the same LAN. Values of NULL or "" may be used for an empty proxy bypass list.

The following examples show possible uses of the switch:

bitsadmin /setproxysettings MyJob PRECONFIG

bitsadmin /setproxysettings MyJob NO_PROXY

bitsadmin /setproxysettings MyJob OVERRIDE proxy1:80 "<local>"

bitsadmin /setproxysettings MyJob OVERRIDE proxy1,proxy2,proxy3 NULL

/SetReplyFileName Job Path

Specify the path of the file that contains the server reply. Valid only for upload-reply jobs.

/Suspend Job

Suspends the specified job. To restart the job, use the /resume switch.

/TakeOwnership Job

Lets a user with administrative privileges take ownership of the specified job.

/Transfer name [type] [/priority job_priority] [/ACLFlags flags] remote_name local_name

Transfers one or more files. By default, BITSAdmin creates a download job that runs at NORMAL priority. BITSAdmin updates the command window with progress information until the transfer is complete or until a critical error occurs. BITSAdmin completes the job if it successfully transfers all the files and cancels the job if a critical error occurs. BITSAdmin does not create the job if it is unable to add files to the job or if you specify an invalid value for type or job_priority. Note that BITSAdmin continues to run if a transient error occurs. To end BITSAdmin, press Ctrl+C.

Use the name parameter to specify the name of the job.

The type parameter is optional. Use the type parameter to specify the type of job. Specify /download for a download job or /upload for an upload job.

The /priority parameter is optional. To specify the priority of the job, set the job_priority operand to FOREGROUND, HIGH, NORMAL, or LOW.

The /ACLFlags parameter is optional. The flags indicate that you want to maintain the owner and ACL information with the file being downloaded. Specify one or more of the following flags. For example, to maintain the owner and group with the file, set flags to OG.

O — Copy owner information with file.
G — Copy group information with file.
D — Copy DACL information with file.
S — Copy SACL information with file.

To transfer more than one file, specify multiple remote_name-local_name pairs. The pairs are space-delimited.

/Util /Help

Displays the command-line usage for the /Util switches. You can also specify /?.

/Util /GetIEProxy <Account>[/Conn <Connection Name>]

Retrieves the proxy usage for the given service account. This switch shows the value for each proxy usage, not just the proxy usage you specified for the service account.

Use the <account> parameter to specify the service account whose proxy settings you want to retrieve. Possible values are:

LOCALSYSTEM
NETWORKSERVICE
LOCALSERVICE

Use the /conn parameter to specify the modem connection to use. If you do not specify the /conn parameter, BITS uses the LAN connection. Specify the modem connection name immediately following the /conn parameter.

For details on setting the proxy usage for service accounts, see the /Util /SetIEProxy switch.

/Util /RepairService

If BITS fails to start, use this switch to fix known issues with various versions of BITS. For example, this switch resolves errors related to incorrect service configuration and dependencies on LANManworkstation service and the network directory. This switch generates output that indicates the issues that were resolved.

Note that if BITS recreates the service, the service description string may be set to English in a localized system.

/Util /SetIEProxy <Account> <Usage> [/Conn <Connection Name>]

Specify proxy settings to use when transferring files using a service account.

Use the <account> parameter to specify the type of service account whose proxy usage you want to define. Possible values are:

LOCALSYSTEM
NETWORKSERVICE
LOCALSERVICE

Use the <usage> parameter to specify the form of proxy detection to use. Possible values are:

NO_PROXY—Do not use a proxy server.
AUTODETECT—Automatically detect the proxy settings.
MANUAL_PROXY—Use an explicit proxy list and bypass list. Specify the proxy list and bypass list immediately following the usage tag. For example, MANUAL_PROXY proxy1,proxy2 NULL.

The proxy list is a comma-delimited list of proxy servers to use.

The bypass list is a space-delimited list of host names or IP addresses, or both, for which transfers are not to be routed through a proxy. This can be <local> to refer to all servers on the same LAN. Values of NULL or "" may be used for an empty proxy bypass list.
AUTOSCRIPT—Same as AUTODETECT, except it also executes a script. Specify the script URL immediately following the usage tag. For example, AUTOSCRIPT http://server/proxy.js.
RESET—Same as NO_PROXY, except it removes the manual proxy URLs (if specified) and URLs discovered using automatic detection.

Note that each successive call using this switch does not replace the previously specified usage. For example, if you specify NO_PROXY, AUTODETECT, and MANUAL_PROXY on separate calls, BITS uses automatic detection to determine the proxy to use. If automatic detection fails, BITS uses MANUAL_PROXY.

Use the /conn parameter to specify the modem connection to use. If you do not specify the /conn parameter, BITS uses the LAN connection. Specify the modem connection name immediately following the /conn parameter.

The following examples show how to use the /Util /SetIEProxy switch:

bitsadmin /util /setieproxy localsystem AUTODETECT

bitsadmin /util /setieproxy localsystem MANUAL_PROXY proxy1,proxy2,proxy3 NULL

bitsadmin /util /setieproxy localsystem MANUAL_PROXY proxy1:80 "<local>"

/Util /Version [/Verbose]

Displays the version of BITS (for example 2.0) that is running. Use the verbose option to display information about the state of BITS.

/Wrap

Wraps output to fit in a command window. Specify before other switches. By default, all switches, except the /Monitor switch, wrap the output.

Send comments about this topic to Microsoft

Build date: 3/15/2012