English ▼
Skip to page content Skip to main navigation
e.g. "templates" or "datastore"

# DoS Protection Service for Java

The App Engine Denial of Service (DoS) Protection Service enables you to protect your application from running out of quota when subjected to denial of service attacks or similar forms of abuse. You can blacklist IP addresses or subnets, and requests routed from those addresses or subnets will be dropped before your application code is called. No resource allocations, billed or otherwise, are consumed for these requests.

Do not use this service for security. It is designed for quantitative abuse prevention, such as preventing DoS attacks, only. Some requests from blacklisted users may still get through to your application.

- About dos.xml
- Limits
- Uploading DoS Configuration
- Viewing Uploaded DoS Configuration in the Administration Console
- Viewing Top Users in the Administration Console

By default, App Engine serves a generic error page to to blacklisted addresses. You can configure your app to serve a custom response instead. For details, see Custom Error Responses.

## About dos.xml

A `dos.xml` file in the `WEB-INF` directory of your application (alongside `appengine-web.xml`) configures DoS Protection Service blacklists for your application. The following is an example `dos.xml` file:

    <?xml version="1.0" encoding="UTF-8"?>
    <blacklistentries>
      <blacklist>
        <subnet>1.2.3.4</subnet>
        <description>a single IP address</description>
      </blacklist>
      <blacklist>
        <subnet>1.2.3.4/24</subnet>
        <description>an IPv4 subnet</description>
      </blacklist>
      <blacklist>
        <subnet>abcd::123:4567</subnet>
        <description>an IPv6 address</description>
      </blacklist>
      <blacklist>
        <subnet>abcd::123:4567/48</subnet>
        <description>an IPv6 subnet</description>
      </blacklist>
    </blacklistentries>

For an XSD describing the format, check the file `docs/dos.xsd` in the SDK.

A `dos.xml` file consists of a number of blacklist entries. A blacklist entry has a `<subnet>`, and can optionally specify a `<description>`. The description will be visible in the Admin Console. The `<subnet>` is any valid IPv4 or IPv6 subnet in CIDR notation.

## Limits

You may define a maximum of 100 blacklist entries in your configuration file. Uploading a configuration file with more than 100 entries will fail.

## Uploading DoS Configuration

You can use `AppCfg` to upload DoS configs. When you upload your application to App Engine using `AppCfg update`, the DoS Protection Service is updated with the contents of `dos.xml`. The new config will be viewable using the Administration Console straight away, but may take a few minutes to take effect. You can update just the DoS configuration without uploading the rest of the application using `AppCfg update_dos`.

To delete all blacklist entries, change the `dos.xml` file to just contain:

    <?xml version="1.0" encoding="UTF-8"?>
    <blacklistentries/>

## Viewing Uploaded DoS Configs in the Administration Console

The Administration Console allows you to view your current DoS configuration, if you have uploaded one. Select the "Blacklist" link from the side menu, and you should see a table of blacklisted subnets/IP addresses and their associated descriptions from your configuration file.

## Viewing Top Users in the Administration Console

The Administration Console also allows you to view the top users that have recently been hitting your site, even if you haven't uploaded a DoS configuration. Select the "Blacklist" link from the side menu, and you should see a table of the top IP addresses that have been hitting your application and how many requests have been recorded. It will be below the table of blacklists, if any. IP addresses that you have blacklisted will not show up in this table.