calkeo / laravel-cloudflare-ddns
This package facilitates dynamic DNS (DDNS) for Cloudflare with no third-party integrations. The package interacts directly with the Cloudflare API to sync the current system's IP address with your Cloudflare DNS records.
Fund package maintenance!
calkeo
Requires
- php: ^8.0
- illuminate/contracts: ^8.0
- spatie/laravel-package-tools: ^1.4.3
Requires (Dev)
- brianium/paratest: ^6.2
- nunomaduro/collision: ^5.3
- orchestra/testbench: ^6.15
- phpunit/phpunit: ^9.3
- spatie/laravel-ray: ^1.9
- vimeo/psalm: ^4.4
This package is auto-updated.
Last update: 2024-04-09 05:57:00 UTC
README
This package facilitates dynamic DNS (DDNS) for Cloudflare with no third-party integrations. The package interacts directly with the Cloudflare API to sync the current system's IP address with your Cloudflare DNS records.
Use Cases
This package can be used for multiple purposes. For instance:
- Running a server on your home network that you want to be accessible to the public.
- Automatically updating your DNS records when you deploy or migrate a site to a new server.
Prerequisites
- PHP 8
- Laravel 8
Installation
Install the package via composer:
composer require calkeo/laravel-cloudflare-ddns
Publish the config file and migrations:
php artisan vendor:publish --provider="Calkeo\Ddns\DdnsServiceProvider"
Run the migrations:
php artisan migrate
Configuration
The configuration file can be found at config/cloudflare_ddns:
return [ /** * The Cloudflare API token for the account that has privileges to manage * the domains that you add to this file. */ 'cloudflare_api_token' => env('CLOUDFLARE_API_TOKEN'), /** * The amount of time in seconds that the public IP address is cached for * each time the ddns:sync command is executed. */ 'cache_duration' => env('DDNS_CACHE_DURATION', 60), /** * The domains to sync with this system's IP address. */ 'domains' => [ [ 'domain' => '', // The domain that the DNS records will be synced with. 'sync_interval' => 5, // The interval in minutes for which this domain's records will be updated 'records' => [ [ 'name' => '', // DNS record name 'type' => '', // DNS record type 'ttl' => 1, // Time to live for DNS record. Value of 1 is 'automatic' 'proxied' => true, // Whether the DNS record is proxied through Cloudflare ], ], ], ], ];
cloudflare_api_token
(string)
A Cloudflare API token that has sufficient privileges to access the DNS records for the domains listed in the config file. How to generate a Cloudflare API token.
cache_duration
(integer)
The amount of time in seconds that the public IP address is cached for each time the ddns:sync command is executed.
The IP address is automatically flushed from the cache each time the ddns:sync command is executed. Because an external network request has to be made in order to retrieve the public IP address, increasing the cache duration will increase performance.
domains[]
(array)
The domains to be synced. A domain is referred to as a Zone within Cloudflare.
domains[][domain]
(string)
The base domain name, also referred to as the Zone. This must be the base of the domain as any subdomains will be configured within the records array.
domains[][sync_interval]
(integer)
How often (in minutes) the domain's DNS records will be synced with the server's public IP address.
domains[][records]
(array)
The DNS records to be synced for the domain.
A record will be synced if there is already an existing DNS record in Cloudflare for this domain that matches the type and name specified for the record in the config file.
domains[][records][name]
(string)
The DNS record name.
For instance:
- Record name
wwwforwww.domain.com - Record name
mysubdomainformysubdomain.domain.com
domains[][records][type]
(string)
The DNS record type. Valid types are:
AAAAACNAMEHTTPSTXTSRVLOCMXNSSPFCERTDNSKEYDSNAPTRSMIMEASSHFPSVCBTLSAURI
domains[][records][ttl]
(integer)
The DNS record TTL (time-to-live). Setting this value to 1 sets the DNS record TTL to 'automatic'.
domains[][records][proxied]
(boolean)
Whether the DNS record should be proxied through Cloudflare's network.
A brief explanation of Cloudflare DNS proxying (source):
The DNS proxied means it will be shown a Cloudflare IP if you look it up. Thus all attacks at that domain will DDoS Cloudflare and not you host directly.
Non proxied means all traffic goes directly to your own IP without Cloudflare being a safety net in front.
The upside of proxied is that you will enjoy the Coudflare benefits but you can not make a direct connection to your IP, which means any custom ports wont work.
Non proxied has the advantage of being able to use custom ports to connect as it will connect to your IP directly.
If you are using this package to setup DDNS for your home network, you should take note from the above, that if you proxy your IP address through Cloudflare then you cannot use custom ports. Read about the ports available whilst proxying through Cloudflare.
Usage
To continually sync your configured domains, it is recommended to create a scheduled task that runs the ddns:sync command every minute.
// App/Console/Kernel.php protected function schedule(Schedule $schedule) { $schedule->command('ddns:sync')->everyMinute(); }
The package will only sync with a domain in Cloudflare if the domain has not yet been synced, or if it is due to run based on the sync_interval value set for the domain in the config file.
An individual record will also not be updated if it is determined that there has been no change in IP address, and if the ttl and proxied values for the record in the config file are up-to-date in Cloudflare.
Roadmap
| Feature | Status |
|---|---|
| Allow creation of new records | Upcoming |
| Support custom IP resolvers | Upcoming |
| Event Broadcasting | Upcoming |
Changelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
Credits
License
The MIT License (MIT). Please see License File for more information.