Background Intelligent File Transfer Service (BITS)

The Background Intelligent Transfer Service (BITS) has two role services: the Compact Server and the IIS Server Extension. The Compact Server is a stand-alone HTTP or HTTPS file server, whereas the IIS Server Extension is an Internet Information Services (IIS) plug-in that requires a server running IIS.

IIS Server Extension

The BITS IIS Server Extension lets you configure a server that is running IIS to allow BITS clients to perform background, resumable file uploads to IIS virtual directories. On completion of a file upload, the BITS Server can notify a Web application of the newly uploaded file. This allows the application to process the uploaded file. The Web application can then optionally reply to the client responsible for the upload. See the BITS IIS Server Extension section for information.

Compact Server

The BITS Compact Server is a stand-alone HTTP or HTTPS file server, which allows applications to host files for BITS clients to download, and allows the asynchronous transfer of a limited number of large files between computers. See the BITS Compact Server section for information.

Additional resources

  • Background Intelligent Transfer Service http://go.microsoft.com/fwlink/?LinkId=140888

  • BITS Reference http://go.microsoft.com/fwlink/?LinkId=140985


BITS IIS Server Extension

The Background Intelligent Transfer Service (BITS) IIS Server Extension lets you configure an Internet Information Services (IIS) server to allow BITS clients to perform background, resumable file uploads to IIS virtual directories. Upon completion of a file upload, BITS Server can notify a Web application of the new file via the BITS Upload Protocol extension for HTTP POST. Your Web application can then optionally reply to the client's posting. For information about the BITS Upload Protocol extension for HTTP POST, see.http://go.microsoft.com/fwlink/?LinkId=143105.

To install BITS IIS Server Extension

  1. In the Features Summary section of Server Manager, click Add Features.

  2. In the Add Features Wizard, select Background Intelligent Transfer Service (BITS) and IIS Server Extension.

  3. Follow the wizard instructions that include installing required software (if indicated). For more information about how to use the Add Features Wizard, refer to the Server Manager online Help.

Configurable Options

Configurable options for the IIS Server Extension include limiting uploaded file size, automatic deletion of incomplete files after a predefined time period, and server farm support. For more information, see the following sections.

  • BITS IIS Server Extension Permissions

  • Enable or Disable BITS IIS Server Extension

  • Customize BITS IIS Server Extension Settings

To remove BITS IIS Server Extension

  1. In the Features Summary section of Server Manager, click Remove Features.

  2. In the Remove Features Wizard, clear the Background Intelligent Transfer Service (BITS) check box and then click Next.

  3. Click Remove, and when you are prompted, click Close to exit the Remove Features Wizard.

  4. Restart the server to complete the BITS feature removal process. For more information about how to use the Remove Features Wizard, refer to the Server Manager online Help.


Enable or Disable BITS IIS Server Extension

The Background Intelligent Transfer Service (BITS) IIS Server Extension lets you configure an IIS server to let BITS clients to perform or resume background file uploads to IIS virtual directories. Upon completion of a file upload, BITS Server can notify a Web application of the new file (through a POST to a configurable URL) in order to process the uploaded files. Your Web application can then optionally reply to the client's posting.

After you have installed BITS IIS Server Extension, you enable it and customize the settings as needed for your environment. For installation instructions, see BITS IIS Server Extension. You can disable BITS IIS Server extension if it is necessary by clearing the Allow clients to upload files check box.

To enable BITS IIS Server Extension

  1. Browse to the virtual directory in IIS Manager.

  2. From the features view of the virtual directory, double-click BITS Uploads.

  3. Select the Allow clients to upload files check box, and then click Apply.

By default, BITS IIS Server Extension uses the settings from the parent Web site of the virtual directory. If these settings are not present, then BITS Server uses its default settings.

You can change the behavior of BITS Server for the virtual directory by selecting the Customize Settings option. For information about these settings, see Customize BITS IIS Server Extension Settings.

To disable BITS IIS Server Extension

  1. Browse to the virtual directory in IIS Manager.

  2. From the features view of the virtual directory, double-click BITS Uploads.

  3. Clear the Allow clients to upload files check box, and then click Apply.

See Also

  • BITS IIS Server Extension


Customize BITS IIS Server Extension Settings

Use the BITS Uploads page to customize BITS IIS Server Extension settings for a specific virtual directory. You can configure file size limitations, notifications, cleanup frequency, and server farm support.

Upload Job Settings

The settings in this section allow you to configure the maximum size of uploaded files, determine when incomplete jobs are deleted, and allow existing files to be overwritten by an upload job.

User interface name Description

Maximum file size

Defines the maximum size of a file that can be uploaded in a single BITS Server job. By default, there is no maximum file size.

Delete incomplete jobs after

Defines how long BITS Server will wait until cleaning up incomplete upload files. The time-out is checked every time that the cleanup process is scheduled to run. Use the options in the Cleanup section to configure the frequency with which the cleanup process should be run for this virtual directory.

Allow files to be overwritten

This setting defines whether BITS Upload server lets existing files be overwritten in the virtual directory. This setting is disabled by default.This prevents unauthorized users from overwriting legitimately uploaded files by uploading a file that has the same name. Attempts to overwrite a file result in the second upload job failing. When two upload jobs have the same destination file name, the second upload job fails, even if an overwriting attempt is unintentional. If you enable this setting, you let files be overwritten.

Be aware that by enabling this setting, BITS Upload server still cannot write to files outside the virtual directory, and unauthorized users cannot overwrite the system’s files using BITS Upload server.

Notifications

By enabling notifications, you can configure BITS Server to send a notification by way of an HTTP POST to a URL you specify when a file is uploaded to the virtual directory.

User interface name Description

Enable notifications

Enables notifications for this virtual directory. The Notification type and Notification URL settings are both required if this setting is enabled.

Notification type

Configures the kind of notification to perform after the job is finished.

  • Send the file name: The server passes the path of the completed upload file to the URL that is specified by the Notification URL setting. The server may return a file to the client as a response.

  • Send the file contents: The server passes the completed upload file to the URL that is specified by the Notification URL as the entity body of the HTTP POST. The response entity is sent to the client.

Notification URL

Specifies the URL to which you want to pass the completed upload file by using an HTTP POST request if the Notification type is Send the file contents or Send the file name. The URL may be absolute or relative. If the URL is relative, then the original request URL is used as the base.

Cleanup

BITS Server checks for and deletes incomplete upload jobs that have timed out. If an upload exceeds the default setting of 12 hours, or the value you specify in the Scan for incomplete jobs every setting, BITS Server automatically cancels the upload and deletes any partial file contents. This setting is not affected by IIS property inheritance and applies only to the virtual directory.

User interface name | Description
Use default cleanup schedule | Configures BITS Server to scan for incomplete uploads older than 12 hours. If an incomplete upload exceeds this setting, BITS Server automatically cancels the upload and deletes any partial file contents at the time you specify in the Delete incomplete jobs after setting.
Use custom cleanup schedule | Configures BITS Server to scan and delete at the interval you specify.
Scan for incomplete jobs every | Configures BITS Server to scan for incomplete uploads older than the interval you specify. If an incomplete upload exceeds this setting, BITS Server automatically cancels the upload and deletes any partial file contents at the time you specify in the Delete incomplete jobs after setting.
Enable cleanup to limit the number of sessions per user | Configures BITS Server to remove jobs uploaded by a user that exceed the value specified in Limit on the number of sessions per user.
Limit on the number of sessions per user | Specifies how many active upload jobs a user may submit to the BITS Server.
Note

You can manually run a cleanup task by clicking Run Cleanup from IIS Manager Actions pane. This immediately starts a check for files that have had no progress since the time-out period. To remove all incomplete files for this virtual directory, set the Delete incomplete jobs after setting to 0 before you run the cleanup.

Server Farm Support

If it is enabled, this setting informs the client to try to reconnect to the same server instead of the original upload URL that was used by the client. This lets clients that are uploading to server farms to continue uploading to the same server where the upload started.

Server farms can be configured in one of two ways:

  1. By using a shared volume for the upload virtual directory

  2. By using server local storage for the uploaded files

If you want to use local storage, then this option will enable the client to reconnect to the same server computer in the server farm. We recommend that you enable and then configure this feature before you upload to server farms and use local storage.

User interface name Description

Enable server farm support

Enables BITS Server uploads support for server farms.

Reconnect to server

Specifies the public IP address to use for reconnecting to this server. A common configuration for a server will have two IP addresses: one that is outward pointing and that is reachable by client systems, and one that is part of the inner (protected) network. Specify the outward-pointing IP address here.

Note

You can specify a DNS name here only if each computer in your Web farm has an independent DNS name that is resolvable by the client computers.

Use original server after

If a client cannot reconnect to the server at the Reconnect to server for this period of time, then the clients will revert to the original DNS name they specified in the upload URL.

See Also

  • BITS IIS Server Extension Permissions


BITS IIS Server Extension Permissions

IIS lets a user set the script and run permissions on a virtual directory separately from its write permissions. Typically, administrators who want to allow script and program execution on a virtual directory disallow writing to that virtual directory (this keeps clients from uploading executable scripts or programs to a directory and executing them). However, when a virtual directory is BITS Server enabled, even though write permissions on the virtual directory have been disallowed, clients can write to this directory by using BITS Server.

To protect the server, BITS Server disables all script and run permissions on a BITS upload–enabled virtual directory. To help secure this virtual directory, BITS Server confirms that these permissions are disabled before responding to any client request for uploading data. If these permissions are enabled at any time, BITS Server will then deny all upload requests until the permissions are disabled again. Every time that the BITS Server denies a request in such an environment, it will write a log entry in the IIS logs.

See Also

  • Enable or Disable BITS IIS Server Extension
  • BITS IIS Server Extension


BITS Compact Server

The Background Intelligent Transfer Service (BITS) Compact Server is a stand-alone HTTP or HTTPS file server that allows the asynchronous transfer between computers of a limited number of large files.

BITS Compact Server is designed for use by enterprise and small business customers under these conditions:

  • The anticipated usage is a maximum of 25 concurrent connections, and a maximum of 100 total connections per server.

  • File transfers occur between computers in the same domain or mutually-trusted domains.

  • The file transfer functionality is not intended for use on Internet-facing clients.

If your file transfer volume is higher or you want to have additional administrative control and file transfer functionality, install the BITS IIS Server Extension.

To install BITS Compact Server

  1. In the Features Summary section of Server Manager, click Add Features.

  2. In the Add Features Wizard, select Background Intelligent Transfer Service (BITS) and Compact Server.

  3. Follow the wizard instructions that include installing required software if indicated. For more information about how to use the Add Features Wizard, refer to the Server Manager online Help.

Optionally, you can install BITS Compact Server using Windows PowerShell cmdlets. For information about how to use cmdlets, see the Windows PowerShell Programmer’s Guide at http://go.microsoft.com/fwlink/?LinkId=143122.

Configurable Options

BITS Compact Server uses the HTTP Server API to create URLs, receive HTTP requests, and send HTTP responses. The API consists of two interfaces ICompactServer and ICompactServerUrlGroup. The first interface is used to create URL groups and the second interface is used to add URLs to the URL group and to configure some properties. You also use the API to enable authentication, bandwidth limit, and connection limits on the URL groups. There is no user interface.

For more information about BITS Compact Server configurable options, see Customize BITS Compact Server.

To remove BITS Compact Server

  1. In the Features Summary section of Server Manager, click Remove Features.

  2. In the Remove Features Wizard, clear the Background Intelligent Transfer Service (BITS) check box and then click Next.

  3. Click Remove, and when you are prompted, click Close to exit the Remove Features Wizard.

  4. Restart the server to complete the BITS feature removal process. For more information about how to use the Remove Features Wizard, refer to the Server Manager online Help.

See Also

  • Background Intelligent File Transfer Service (BITS)


Customize BITS Compact Server

The BITS Compact Server provides the following customizable features:

  • Programmatic ways to expose files for download

  • Authenticated and encrypted downloads

  • Remote management functionality

These features enable Microsoft System Center Virtual Machine Manager (VMM) to manage virtual machine hosts without an agent, and also offer options to system administrators for datacenter automation using other compatible applications.

BITS Compact Server API

The BITS Compact Server API consists of two interfaces ICompactServerSession and ICompactServerUrlGroup. The first interface is used to create URL groups. The second interface is used to add URLs to the URL group and to configure some properties. There is no user interface.

By using the BITS Compact Server API, you will configure the controlling application to do the following tasks:

  1. CoCreate ICompactServer.

  2. Call ICompactServer::CreateUrlGroup.

  3. Call ICompactServerUrlGroup::SetAuthentication.

  4. Call ICompactServerUrlGroup::AddUrl.

For detailed information about the BITS Compact Server API, see Background Intelligent Transfer Service at http://go.microsoft.com/fwlink/?LinkId=140888 and BITS Reference at http://go.microsoft.com/fwlink/?LinkId=140985.

You can also configure BITS Compact Server by using the WMI provider API and WMI Powershell cmdlets. See the BITS Compact Server Remote Management section for information.

Logging

If you contact Microsoft Support, the support technician may ask you to send logs to Microsoft. For debugging, BITS Compact Server creates a log file in %windir%\System32\LogFiles\CompactServer. To enable logging, set the following values as directed by the support technician in the registry at HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\Current Version\CompactServer:

LogFileFlags

LogFileSize

LogFileMinMemory

Remote Management of the BITS Compact Server

See the BITS Compact Server Remote Management section for information about remote management of file transfers on the server and on the client.

See Also

  • BITS Compact Server


BITS Compact Server Remote Management

The BITS Compact Server with BITS Remote Management helps secure remote file transfers. BITS Remote Management uses BITS Windows Management Instrumentation (WMI) providers to let a system administrator or a controller application remotely create BITS jobs on the clients and publish files for hosting on the BITS Compact Server. BITS WMI providers can remotely transfer files from one remote computer to another remote computer by using the BITS client in conjunction with the BITS Compact Server. This feature is primarily designed to work with Microsoft System Center Virtual Machine Manager (VMM) as the controller application. However, any application that can use the BITS WMI provider can also serve as the controller application.

Important

All remote management activities must be run under an account in the Administrators group. Any requests from accounts that are not in the Administrators group will be denied access.

Architectural Overview

The following diagram shows how a controller application on a remote computer can securely manage files transfers on a client and on the BITS Compact Server. In this example, the controller application deploys a job on the server and a client through WS-Management. (WS-Management is the Microsoft implementation of Web Services-Management protocol.) The remote calls are received by the WS-Management (WSMAN) service on the server and client computers. The calls are passed to the WMI service that in turn invokes the BITS WMI provider to service the requests.

The controller application can use either WS-Management or WMI DCOM to deploy a job. In either case, configuration is needed on the remote computer to accept incoming requests. For information about how to connect to WMI on a remote computer see http://go.microsoft.com/fwlink/?linkid=122134. For information about configuration for Windows Remote Management see http://go.microsoft.com/fwlink/?linkid=122026.

To transfer a file, the controller application establishes connections with the WMI providers running on the client and on the server computers. It creates jobs to start the file transfer. A job on a server is defined as a URL hosted for a file residing on the server. A job is identified by the following:

  • URL Group: A URL group hosts a URL to service a file. This is a combination of the HTTP.SYS URL group and the request queue. For example, a URL group such as http://+:80/Carmine can be specified during the creation. The protocol to be used and the port on the host are also specified in the URL group. Be aware that two-level URL groups, such as http://+:80/Carmine1/Carmine2 are not supported.

  • Source file: The name of the file to be hosted on the server by the job.

  • URL suffix: a suffix which a client uses to uniquely identify the job

  • The URL that the client specifies to download a job consists of:

    • Protocol to be used: HTTP or HTTPS

    • Hostname: Name of the server

    • URL group: The namespace under which a job is hosted on the server

    • URL suffix: The suffix identifying the job created on the server

For more information about URL Prefix Strings, see http://go.microsoft.com/fwlink/?LinkId=143141.

The following sections describe how to create, monitor, and delete jobs.

Job Creation on the Server

  1. The controller application establishes a connection to root\Microsoft\Bits namespace on the BITS Server. The WMI Server Provider authenticates the remote token to check for administrative rights. The controller application sets the SSL certificates for the HTTPS port on which downloads will be serviced.

  2. The controller application requests that the WMI server provider create a URL Group on the server that will let URLs be hosted on the server. The authentication mechanism for the URL Group can be set at this point.

  3. The controller application requests that the WMI server provider create a URL that will allow a specific file residing on the server to be made available to client computer processes.

  4. The provider creates a URL Group by using COM interfaces on the server and registers a unique URL suffix in the URL Group. The SDDL and certificate authorization can be set for each unique URL.

  5. Any new jobs that are added to this URL Group will share the same URL Group and its settings. The host is now configured and listens for any requests from the client for the registered URL.

Job Creation on the Client

  1. The controller application establishes connection to root\Microsoft\Bits namespace on the client computer.

  2. The WMI client provider authenticates the remote token to check for administrative permissions. Be aware that typically WMI providers also impersonate the incoming client before providing any data. In this case, however, servicing the client happens in the context in which WMI is opened (Local System). This allows for otherwise blocked remote calls to be serviced by BITS.

  3. The controller application requests that the WMI client provider create a job that will let a specific file residing on the server to be downloaded to client computer by using the BITS service.

  4. The provider establishes a connection with the BITS service through the exposed COM interfaces.

  5. The provider impersonates the service account under which the controller application expects the BITS job to be running.

  6. The BITS job will be created for the requested URL on the server.

  7. The authentication certificate can be added to the job.

  8. Authentication credentials can be set for the job in non-trusted domain scenarios.

  9. The BITS job is resumed immediately after it is created and the file transfer starts.

Job Monitoring

  1. The controller application monitors the BITS job created through the status property made available by Client provider. If the job encounters a transient error, the controller application can fetch the error code, cancel the BITS job, and go to cleanup.

  2. If the file has been successfully transferred, the controller application can do cleanup.

Job Cleanup

  • Cleanup on the client occurs when the controller application moves the BITS job to a cleanup stage. If the job is in BG_JOB_STATE_TRANSFERRED state, the job can be moved to completed state. Otherwise the job can be canceled.

  • Cleanup on the server is performed by the controller application requesting the server provider to cancel the hosted URL. The URL registered with the group is deleted. The client can delete the URL Group as well, therefore deleting all the URLs served by that URL Group.

Additional resources

For detailed information about the BITS WMI call sequence and methods, see Background Intelligent Transfer Service at http://go.microsoft.com/fwlink/?LinkId=140888 and BITS Reference at http://go.microsoft.com/fwlink/?LinkId=140985.

For general information about using WMI see http://go.microsoft.com/fwlink/?linkid=136379.

See Also

  • Customize BITS Compact Server