Skip to main content
Code42 Support

Configure network-based device backup rates with the Code42 API

Available in:

  • CrashPlan PRO
    • Standard
    • Premium
    • Enterprise
Applies to:

Overview

Administrators can configure data transfer rates for device backups based on the device location and the backup destination. This tutorial explains how to create the JSON data that configures those settings, and how to send the JSON to your authority server via the Code42 API.

Configuring network-based device backup rates has many advantages, including:

  • The ability to finely control bandwidth use for any combination of location, destination, day, and time.
  • The ability to prevent traveling users from saturating Internet connections with backup activity when visiting locations with lower available bandwidth.
  • The ability to configure sending limits not tied to organizational hierarchy.

To configure these settings via the administration console instead of the Code42 API, see Configuring Device Networks.

Considerations

  • Network-based backup rates require an on-premises authority server and require SYSADMIN permissions to enable.
  • Enabling network-based backup rates overrides existing settings defined in the Settings > Device Backup > Network section of the administration console and apply globally to your entire Code42 environment.
  • The sending rates referenced throughout this article apply only to device backup. Sending limits do not apply to devices restoring files.
  • Network-based backup rates require Code42 app version 4.6 or later (4.x-series) or 5.2 or later (5.x-series). Older versions of the Code42 app will use the settings that were in place before network-based backup rates were enabled. However, you will be unable to edit the old settings via the administration console.
Advanced process
This is an advanced process that requires specialized knowledge of network configuration, the Code42 API, and JSON-formatted data. We strongly recommend engaging our PRO Services team before configuring these settings in your Code42 environment.

Understand network-based backup rates

Network-based backup rates depend on two major concepts: sites and destinations.

  • A site is a specific IP address, IP range, or subnet to which a device connects. This indicates the device location. For example, the network within a company's corporate headquarters could be defined as one site, and the network at a remote office could be defined as another site.
  • A destination is the storage location of the user's archive, or more specifically, a grouping of Code42 servers and store points on a single LAN or at a single data center that receives backup data from user devices. For example, to support international users, a company might have three different destinations: one each in the United States, Germany, and China.

When you set network-based backup rates, you define the maximum data transfer rate (in kbps) for user devices at specific sites that send backup data to specific destinations.

Before you begin

  • Identify the sites for which you want to define a maximum device sending rate. Obtain the IP addresses or subnet for each site.
  • (Optional) Identify the backup destinations for which you want to define a maximum device sending rate. Obtain the destination GUID or IP address for each destination. (If you do not define sending rates by destination, devices use the same backup rate for all destinations.)
  • Determine the desired maximum sending rate in kbps for:
    • Each combination of backup destination and device location
    • When users are present and when they are away from their devices
    • Peak and off-peak times of day
      Consult your network administrator for assistance determining the appropriate maximum sending rates for your environment.

Part 1: Define network-based backup rates

Network-based backup rates are defined by assembling a set of JSON name:value pairs, comprising three main sections:

  • Default sending rates
  • Site details
  • Destination details

The configuration options are highly flexible, allowing for complex combinations of sites and destinations. However, the examples in the steps below are limited to single values for simplicity. More complex examples are provided at the end of this article.

Step 1: Enable network-based backup rates

The first name:value pairs to define in the JSON data are two enabled flags and the JSON version:

"enabled":true,
"scheduleEnabled":true,
"version":1.0

Enabled can be either true or false and determines whether or not the Code42 server uses the network-based rates defined in the JSON (true) or the existing values from the administration console (false).

ScheduleEnabled can be either true or false and determines whether or not the Code42 server uses the peak and off-peak times and rates for each site (true) or instead uses the wanRate, lanRate, and siteRate at all times (false).

version defines the version of JSON. This should always be 1.0.

Step 2: Define default sending rates

Default sending rates determine the device backup rate for all device and destination combinations not explicitly defined in the list of sites (see steps 3 and 4 below).

Because it would be highly impractical (and nearly impossible) to pre-define sending rates for every possible device IP address, the default sending rates apply to situations where there is not a match in the list of defined sites. Practically speaking, this means if you define sending rates for all known company offices, a user device connecting to the Internet from a home or public network would use the default sending rates, because the device's IP address won't match any defined sites.

The example below defines away and present sending rates for both WAN and LAN connections. (Linux devices always use the away setting.)

"defaultSite":{
    "lanRate":{
      "userAwayKilobitsPerSecond":777,
      "userPresentKilobitsPerSecond":555
    },
    "wanRate":{
      "userAwayKilobitsPerSecond":333,
      "userPresentKilobitsPerSecond":111
    }
  }

Step 3: Define sites

Each site definition consists of four JSON name:value pairs:

  • enabled: Setting to true enforces the defined sending rates. Setting to false does not apply these values.
  • name: An administrator-defined label for the site.
  • clientNetworks: This defines the specific IP address, IP range (in CIDR notation), or subnet to which a user device connects. Both IPv4 and IPv6 addresses are supported.
  • siteRate
    • userAwayKilobitsPerSecond defines the maximum data transfer rate when the user is away from the device. (Linux devices always use the away setting.)
    • userPresentKilobitsPerSecond defines the maximum data transfer rate when the user is present at the device.

The example below defines away and present sending rates for a site named "Site 1," which applies to any device within the IP address range 192.0.2.0/24.

  "sites":[
    {
      "enabled":true,
      "name":"Site 1",
      "clientNetworks":["192.0.2.0/24"],
      "siteRate":{
        "userAwayKilobitsPerSecond":200,
        "userPresentKilobitsPerSecond":50
      }
    }    
  ]

To define multiple sites, create a comma-separated list of the JSON objects within the square brackets. Multiple-site examples are included at the end of this article.

Step 4: Define destinations (optional)

Defining destinations allows you to configure a single device to use unique sending rates for each backup destination. If you do not define a destination, the device will use the same backup rate for all destinations.

The destination definition consists of two JSON name:value pairs: the first part specifies the destination, and the second part specifies the sending rate.

  • You must choose to define the destination either by IP address or destination GUID. (Definitions cannot contain both serverNetworks and destinationUids value pairs.)
    • serverNetworks: This defines the server IP address of the destination. Both IPv4 and IPv6 addresses are supported.
    • destinationUids: This defines the destination GUID of the destination.
  • destinationRate
    • userAwayKilobitsPerSecond defines the maximum data transfer rate when the user is away from the device. (Linux devices always use the away setting.)
    • userPresentKilobitsPerSecond defines the maximum data transfer rate when the user is present at the device.

The example below defines away and present sending rates for devices connecting to a destination with the IP address 192.0.4.0.

"destinations":[
        {
          "serverNetworks":["192.0.4.0"],
          "destinationRate":{
            "userAwayKilobitsPerSecond":1605,
            "userPresentKilobitsPerSecond":1405
          }
        }
      ]

To define multiple destinations within a single site, create a comma-separated list of the JSON objects within the square brackets. Multiple-destination examples are included at the end of this article.

Step 5: Define schedules (optional)

Requires Code42 app version 4.7 or later (4.x-series) or 5.3 or later (5.x-series).

Scheduled sending limits enable you to define schedules with different maximum rates for peak and off-peak times. This is useful for throttling backup traffic when specific networks and destinations are busy with higher priority network activity.

Schedules apply only to explicitly defined sites and destinations.

A schedule object has five parts:

  • siteScheduleEnabled: The valuetrue means that the schedule applies to this site;false means the schedule data is ignored.
  • timeZone: The time zone that governs the day, hour, and minute values in a schedule. You can specify a timezone in either of two formats:
    • +/- HH:MM: RFC 3339/ISO 8601 format, hours and minutes ahead of or behind UTC time. For example:
      Minneapolis, U.S., is at-06:00; London, U.K. is at00:00; Sydney, Australia is at+10:00. (Does not account for daylight saving time).
    • IANA timezone names: See the list at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones. For example: Minneapolis, U.S., is atUS/Central; London, U.K., is at Europe/London; Sydney, Australia, is at Australia/ACT.
  • siteSchedule: The schedule object has one to seven child objects, each named for a day of the week. Each day object has three name:value pairs:
    • included: The value true means that this day's peak-time definition applies to this site;false means it does not apply.
    • startTimeOfDay and endTimeOfDay: The times that peak hours and the associated peak rates begin and end on each day. Specify times in the form hh:mm, using the 24-hour clock.
  • sitePeakRate: During the peak times defined in the siteSchedule, the maximum transfer rate for data coming from each device at the site. Off-peak rates are defined by the siteRate, the same object that applies when there is no schedule and no peak rate.
  • destinationPeakRate: During the peak times defined in the siteSchedule, the maximum transfer rate for data from each device to the destination.

In the example below, devices connecting from 192.0.2.0/24 use peak times of 07:00 to 18:00, two days per week, and the maximum transfer rate during those times is 25 kbps (user present) and 100 kbps (user away). Backups going to 192.0.4.0, however, will move at a maximum of 20 kbps (present) or 90 kbps (away) during peak times.

 "sites":[
    {
      "siteScheduleEnabled":true,
      "timeZone":"-06:00",
      "siteSchedule":{
        "monday":{
          "included":true,
          "startTimeOfDay":"07:00",
          "endTimeOfDay":"18:00"
        },
        "tuesday":{
          "included":true,
          "startTimeOfDay":"07:00",
          "endTimeOfDay":"18:00"
        },
      }
      "sitePeakRate":{
        "userAwayKilobitsPerSecond":100,
        "userPresentKilobitsPerSecond":25
      }
      "destinations":[
        {
          "destinationPeakRate":{
            "userAwayKilobitsPerSecond":90,
            "userPresentKilobitsPerSecond":20
          }
        }
      ]
    }    
  ]

Step 6: Prepare the JSON data

Before sending your configured settings to the Code42 server, you must assemble the JSON data from the steps above into a single block of text. Based on the previous steps, here is an example of the complete JSON data. It describes:

  • Default transfer rates for any site outside the explicitly defined sites.
  • An array of site objects that holds one site named Site 1. Site 1 has:
    • One range of client IP addresses
    • One site schedule to define peak and off-peak times of day, Monday through Friday
    • Two pairs of transfer rates: one for peak times, and one for off-peak times
    • An array of destination objects that holds one destination. That destination has:
      • One IP address
      • Two pairs of transfer rates: one for peak times, and one for off-peak times
{
  "enabled":true,
  "version":1.0,
  "defaultSite":{
    "lanRate":{
      "userAwayKilobitsPerSecond":777,
      "userPresentKilobitsPerSecond":555
    },
    "wanRate":{
      "userAwayKilobitsPerSecond":333,
      "userPresentKilobitsPerSecond":111
    }
  },
  "sites":[
    {
      "enabled":true,
      "siteScheduleEnabled":true,
      "timeZone":"-06:00",
      "name":"Site 1",
      "clientNetworks":["192.0.2.0/24"],
      "siteSchedule":{
        "monday":{
          "included":true,
          "startTimeOfDay":"07:00",
          "endTimeOfDay":"18:00"
        },
        "tuesday":{
          "included":true,
          "startTimeOfDay":"07:00",
          "endTimeOfDay":"18:00"
        },
        "wednesday":{
          "included":true,
          "startTimeOfDay":"07:00",
          "endTimeOfDay":"18:00"
        },
        "thursday":{
          "included":true,
          "startTimeOfDay":"07:00",
          "endTimeOfDay":"18:00"
        },
        "friday":{
          "included":true,
          "startTimeOfDay":"07:00",
          "endTimeOfDay":"18:00"
        },
      }
      "siteRate":{
        "userAwayKilobitsPerSecond":200,
        "userPresentKilobitsPerSecond":50
      }
      "sitePeakRate":{
        "userAwayKilobitsPerSecond":100,
        "userPresentKilobitsPerSecond":25
      }
    "destinations":[
        {
          "serverNetworks":["192.0.4.0"],
          "destinationRate":{
            "userAwayKilobitsPerSecond":1605,
            "userPresentKilobitsPerSecond":1405
          }
          "destinationPeakRate":{
            "userAwayKilobitsPerSecond":90,
            "userPresentKilobitsPerSecond":20
          }
        }
      ]
    }
  ],
}
How the Code42 app determines the appropriate sending rate
The Code42 app applies the sending rate for the first match it finds in the list of JSON sites and destinations objects. If the device matches more than one definition, it uses the configuration for whichever site is listed first. If none of the site and destination definitions are a match, the device uses the defaultSite configuration.

Part 2: Enable network-based backup rates via the Code42 API

Resource details

To submit the JSON values for network-based backup rates, use the PUT method of the deviceRateLimitConfiguration resource and include the JSON values as the request body. This can be accomplished with any tool you choose for working with the Code42 API.

Required Parameters
  • Resource name: deviceRateLimitConfiguration
  • Method: PUT
  • Credentials: Your Code42 username and password. You must have SYSADMIN permissions to enable network-based backup rates.
  • Code42 server protocol, host and port: For example, https://master-server.example.com:4285
  • Scope: Can be either system or device.
    • system applies the settings to your entire Code42 environment.
    • device, followed by a device GUID, applies the settings only to a single device and can be useful for testing purposes before applying settings globally. For example: ?scope=DEVICE&guid=1234567891234567
  • Request body:
    • Use your tool of choice to submit the JSON values as the request body. For example, add the body as a parameter to a curl command with the -d flag.
    • Set the content type to JSON. For example: -H "Content-Type: application/json"

For more details, access your Code42 server's API Documentation Viewer by appending "/apidocviewer/#DeviceRateLimitConfiguration" to the website protocol, host and port of your master server. For example: https://master-server.example.com:4285/apidocviewer/#DeviceRateLimitConfiguration

Example: Use Postman to interact with the Code42 API

If you do not have a preferred method for accessing the Code42 API, consider using Postman, an API plugin for the Chrome web browser. Postman works on any operating system with a web browser and does not require specialized programming or scripting experience.

The steps below illustrate how to use Postman to access the Code42 API, but are intended only as an example of one method for enabling network-based backup rates.

From Postman:

  1. Select PUT.
  2. Enter your authority server's URL and port, followed by /api/DeviceRateLimitConfiguration?scope=SYSTEM.
    For example: https://master-server.example.com:4285/api/DeviceRateLimitConfiguration?scope=SYSTEM
  3. Select Authorization > Basic Auth and enter your username and password.
    You must have SYSADMIN permissions to enable network-based backup rates.
  4. Select Body.
  5. Select raw.
  6. Select JSON.
    While not technically required, this assists in identifying potential syntax errors.
  7. Insert the complete JSON into the text area.
  8. Select Send.

Using Postman to enable site-based sending limits via the Code42 API

Update existing values

  1. Submit a GET request to thedeviceRateLimitConfiguration resource. This returns the current values.
  2. Make any necessary updates to the JSON.
  3. Resend the entire JSON block with a PUT request to the deviceRateLimitConfiguration resource (see above example). The newly submitted JSON values override all previous values.

Additional examples

The following example defines sending rates for three different sites ("Minneapolis," "Headquarters," and "Tokyo") and includes both IPv4 and IPv6 addresses in the site definitions.

{
  "enabled":true,
  "version":1.0,
  "sites":[
    {
      "enabled":true,
      "name":"Minneapolis",
      "clientNetworks":[
        "192.0.0.0/24",
        "f400:abcd::/48"
      ],
      "siteRate":{
        "userAwayKilobitsPerSecond":200,
        "userPresentKilobitsPerSecond":50
      }
    },
    {
      "enabled":true,
      "name":"Headquaraters",
      "clientNetworks":[
        "192.0.2.0/24"
      ],
      "siteRate":{
        "userAwayKilobitsPerSecond":100,
        "userPresentKilobitsPerSecond":200
      }
    },
    {
      "enabled":true,
      "name":"Tokyo",
      "clientNetworks":[
        "d600:zxcv::/48"
      ],
      "siteRate":{
        "userAwayKilobitsPerSecond":654,
        "userPresentKilobitsPerSecond":321
      }
    }
  ],
  "defaultSite":{
    "lanRate":{
      "userAwayKilobitsPerSecond":777,
      "userPresentKilobitsPerSecond":555
    },
    "wanRate":{
      "userAwayKilobitsPerSecond":333,
      "userPresentKilobitsPerSecond":111
    }
  }
}

The following example defines sending rates for three sites: "Chicago," "Atlanta," and "New York." Atlanta has a peak rate scheduled for weekdays. New York has two destinations.

{
  "enabled":true,
  "version":1.0,
  "sites":[
    {
      "enabled":false,
      "name":"Chicago",
      "clientNetworks":[
        "192.0.0.0/24"
      ],
      "siteRate":{
        "userAwayKilobitsPerSecond":200,
        "userPresentKilobitsPerSecond":50
      }
    },
    {
      "enabled":true,
      "siteScheduleEnabled":true,
      "timeZone":"-05:00",
      "name":"Atlanta",
      "clientNetworks":[
        "192.0.1.0/24"
      ],
      "siteRate":{
        "userAwayKilobitsPerSecond":100,
        "userPresentKilobitsPerSecond":200
      }
      "sitePeakRate":{
        "userAwayKilobitsPerSecond":80,
        "userPresentKilobitsPerSecond":180
      }
      "siteSchedule":{
        "monday":{
          "included":true,
          "startTimeOfDay":"07:00",
          "endTimeOfDay":"18:00"
        },
        "tuesday":{
          "included":true,
          "startTimeOfDay":"07:00",
          "endTimeOfDay":"18:00"
        },
        "wednesday":{
          "included":true,
          "startTimeOfDay":"07:00",
          "endTimeOfDay":"18:00"
        },
        "thursday":{
          "included":true,
          "startTimeOfDay":"07:00",
          "endTimeOfDay":"18:00"
        },
        "friday":{
          "included":true,
          "startTimeOfDay":"07:00",
          "endTimeOfDay":"18:00"
        },
      }
    },
    {
      "enabled":true,
      "name":"New York",
      "clientNetworks":[
        "192.0.2.0/24"
      ],
      "destinations":[
        {
          "serverNetworks":[
            "192.0.4.0"
          ],
          "destinationRate":{
            "userAwayKilobitsPerSecond":1605,
            "userPresentKilobitsPerSecond":1405
          }
        },
        {
          "serverNetworks":[
            "192.0.6.0"
          ],
          "destinationRate":{
            "userAwayKilobitsPerSecond":1205,
            "userPresentKilobitsPerSecond":1005
          }
        }
      ],
      "siteRate":{
        "userAwayKilobitsPerSecond":350,
        "userPresentKilobitsPerSecond":987
      }
    }
  ],
  "defaultSite":{
    "lanRate":{
      "userAwayKilobitsPerSecond":777,
      "userPresentKilobitsPerSecond":555
    },
    "wanRate":{
      "userAwayKilobitsPerSecond":333,
      "userPresentKilobitsPerSecond":111
    }
  }
}

External resources

  • Was this article helpful?