IP & Subnet Restrictions

Overview

IP and subnet restrictions provide network-level access control for your shared files. You can limit access to specific IP addresses or entire network ranges using CIDR notation, ensuring only authorized networks can access your content.

Use Cases

Restrict file access to corporate office networks
Limit downloads to specific VPN endpoints
Allow access only from trusted data centers
Provide region-specific content distribution
Implement client-specific access controls

Configuration Fields

Access restrictions are configured using two array fields in the Access model (see models/access.go:11-12):

Subnets []string `gorm:"type:text[]"` // Array of subnets
IPs     []string `gorm:"type:text[]"` // Array of IPs

IPs Array

A list of individual IPv4 or IPv6 addresses that are allowed to access the file. Example:

"ips": ["203.0.113.45", "198.51.100.22", "2001:db8::1"]

Subnets Array

A list of network ranges in CIDR notation that are allowed to access the file. Example:

"subnets": ["192.168.1.0/24", "10.0.0.0/8", "2001:db8::/32"]

Creating Restricted Access Links

Identify target networks

Determine which IP addresses or subnets should have access to your file.

Format in CIDR notation

Convert network ranges to proper CIDR notation (e.g., 192.168.1.0/24).

Create access link

Include ips and/or subnets arrays in your access creation request.

Test access

Verify that access works from allowed networks and is blocked from others.

API Examples

curl -X POST https://your-defdrive-instance.com/files/42/access \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Admin Access Only",
    "public": true,
    "ips": ["203.0.113.45"]
  }'

CIDR Notation Reference

CIDR (Classless Inter-Domain Routing) notation specifies IP address ranges using a base IP and prefix length.

Common IPv4 Subnet Masks

CIDR	Subnet Mask	Usable IPs	Description
/32	255.255.255.255	1	Single host
/31	255.255.255.254	2	Point-to-point link
/30	255.255.255.252	2	Small network
/29	255.255.255.248	6	Tiny network
/28	255.255.255.240	14	Very small network
/27	255.255.255.224	30	Small network
/26	255.255.255.192	62	Small network
/25	255.255.255.128	126	Medium network
/24	255.255.255.0	254	Standard subnet
/16	255.255.0.0	65,534	Large network
/8	255.0.0.0	16,777,214	Very large network

Example Subnet Calculations

CIDR: 192.168.1.0/24
Range: 192.168.1.0 - 192.168.1.255
Usable: 192.168.1.1 - 192.168.1.254
Hosts: 254

Access Validation Logic

When a user attempts to access a file via an access link, DefDrive performs network validation checks (see middleware/access_restrictions.go:82-111).

Subnet Check Implementation

func checkSubnetRestriction(access models.Access, c *gin.Context) bool {
    if len(access.Subnets) > 0 {
        ip := c.ClientIP()
        for _, subnet := range access.Subnets {
            _, parsedSubnet, err := net.ParseCIDR(subnet)
            if err == nil && parsedSubnet.Contains(net.ParseIP(ip)) {
                return true
            }
        }
        c.JSON(http.StatusForbidden, gin.H{"error": "Access restricted to specific subnets"})
        c.Abort()
        return false
    }
    return true
}

Process:

Get client’s IP address
Parse each CIDR subnet
Check if client IP falls within any subnet
Allow access if match found
Deny access if no match found

IP Check Implementation

func checkIPRestriction(access models.Access, c *gin.Context) bool {
    if len(access.IPs) > 0 {
        ip := c.ClientIP()
        for _, allowedIP := range access.IPs {
            if ip == allowedIP {
                return true
            }
        }
        c.JSON(http.StatusForbidden, gin.H{"error": "Access restricted to specific IPs"})
        c.Abort()
        return false
    }
    return true
}

Process:

Get client’s IP address
Compare against each allowed IP
Allow access on exact match
Deny access if no match found

If both ips and subnets arrays are empty, no IP restriction is enforced and access is allowed from any IP address (subject to other restrictions).

Restriction Behavior

Combined Restrictions

When both ips and subnets are specified, access is granted if the client IP matches either list:

{
  "ips": ["203.0.113.45"],
  "subnets": ["192.168.1.0/24"]
}

Access allowed from:

203.0.113.45 (exact IP match)
192.168.1.1 through 192.168.1.254 (subnet match)

Empty Arrays

If both arrays are empty or omitted, no IP/subnet restriction is applied:

{
  "ips": [],
  "subnets": []
}

This allows access from any IP address, making it suitable for public file sharing.

Error Responses

Subnet Restriction Denied

{
  "error": "Access restricted to specific subnets"
}

HTTP Status: 403 Forbidden This error occurs when:

The subnets array is not empty
Client IP doesn’t fall within any specified subnet
No matching IP in the ips array

IP Restriction Denied

{
  "error": "Access restricted to specific IPs"
}

HTTP Status: 403 Forbidden This error occurs when:

The ips array is not empty
Client IP doesn’t match any specified IP
No matching subnet in the subnets array

Testing Restrictions

To test your IP restrictions, you can check your current IP:

curl https://api.ipify.org

Then verify access:

curl -v https://your-defdrive-instance.com/ACCESS_LINK_HASH

Be careful when setting IP restrictions. If you lock yourself out, you’ll need to update the access record through the API from an allowed IP or delete and recreate the access link.

Updating Restrictions

You can modify IP/subnet restrictions on existing access links:

curl -X PUT https://your-defdrive-instance.com/access/15 \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Restrictions",
    "public": true,
    "ips": ["198.51.100.99"],
    "subnets": ["192.168.2.0/24"]
  }'

Best Practices

Use Subnets for Organizations - Use CIDR notation for entire office networks rather than listing individual IPs
Combine with Other Restrictions - Layer IP restrictions with TTL, one-time use, and expiration for maximum security
Test Before Sharing - Verify access works from intended networks before distributing links
Document Your Networks - Keep track of which subnets are used for which purposes
Consider Dynamic IPs - Home/mobile users may have changing IPs; subnets may be more reliable than specific IPs
Use /32 for Single Hosts - Specify individual IPs using /32 CIDR notation for consistency

Private Network Ranges

Commonly used private IP ranges (RFC 1918):

10.0.0.0/8 - Large private networks (10.0.0.0 - 10.255.255.255)
172.16.0.0/12 - Medium private networks (172.16.0.0 - 172.31.255.255)
192.168.0.0/16 - Small private networks (192.168.0.0 - 192.168.255.255)

Next Steps

TTL Configuration - Limit access by number of uses
One-Time Links - Create single-use access links
Creating Access Links - Learn about other access restrictions

Get Started

Installation

Core Concepts

Guides

IP & Subnet Restrictions

Overview

Use Cases

Configuration Fields

IPs Array

Subnets Array

Creating Restricted Access Links

API Examples

CIDR Notation Reference

Common IPv4 Subnet Masks

Example Subnet Calculations

Access Validation Logic

Subnet Check Implementation

IP Check Implementation

Restriction Behavior

Combined Restrictions

Empty Arrays

Error Responses

Subnet Restriction Denied

IP Restriction Denied

Testing Restrictions

Updating Restrictions

Best Practices

Private Network Ranges

Next Steps

Build docs developers (and LLMs) love

Get Started

Installation

Core Concepts

Guides

​Overview

​Use Cases

​Configuration Fields

​IPs Array

​Subnets Array

​Creating Restricted Access Links

​API Examples

​CIDR Notation Reference

​Common IPv4 Subnet Masks

​Example Subnet Calculations

​Access Validation Logic

​Subnet Check Implementation

​IP Check Implementation

​Restriction Behavior

​Combined Restrictions

​Empty Arrays

​Error Responses

​Subnet Restriction Denied

​IP Restriction Denied

​Testing Restrictions

​Updating Restrictions

​Best Practices

​Private Network Ranges

​Next Steps

Build docs developers (and LLMs) love

Overview

Use Cases

Configuration Fields

IPs Array

Subnets Array

Creating Restricted Access Links

API Examples

CIDR Notation Reference

Common IPv4 Subnet Masks

Example Subnet Calculations

Access Validation Logic

Subnet Check Implementation

IP Check Implementation

Restriction Behavior

Combined Restrictions

Empty Arrays

Error Responses

Subnet Restriction Denied

IP Restriction Denied

Testing Restrictions

Updating Restrictions

Best Practices

Private Network Ranges

Next Steps