Net::OpenSRS(3pm)

✨ NAME ✨

Net::OpenSRS(3pm) — User Contributed Perl Documentation. Net::OpenSRS — Domain registration via the Tucows OpenSRS HTTPS XML API. That's the whole name vibe. 💅

🌸 Description 🌸

okay so Net::OpenSRS is a wrapper interface to the DNS portions of the Tucows OpenSRS HTTPS XML API. fr fr.

The client library distributed by OpenSRS can be difficult to integrate into a custom environment, and their web interface becomes quickly tedious with heavy usage. This is a clean and relatively quick library to perform the most common API methods described in the OpenSRS API documentation. ate. 💖

💅 Examples 💅

bestie, here's the group-chat demo. Copy-paste energy:

use Net::OpenSRS;

my $key = 'Your_API_Key_From_The_Reseller_Interface';
my $srs = Net::OpenSRS->new();

$srs->environment('live');
$srs->set_key( $key );

$srs->set_manage_auth( 'manage_username', 'manage_password' );

my $cookie = $srs->get_cookie( 'spime.net' );
if ($cookie) {
    print "Cookie:  $cookie\n";
} else {
    print $srs->last_response() . "\n";
}

# do a batch of domain locks
$srs->bulk_lock([ 'example.com', 'example.net', ... ]);

# renew a domain
my $result = $srs->renew_domain( 'example.com' );
...

📝 Notes 📝

🎀 Prerequisites 🎀

This module requires some setup in the OpenSRS reseller environment before it will work correctly. no cap.

🛍️ Reseller account 🛍️

You need to have an OpenSRS account, of course. If you aren't an OpenSRS reseller, this module will be of limited use to you. :) iykyk

🌐 Script API network access 🌐

The machine(s) using this module need to have their public IP addresses added to your 'Script API allow' list in the OpenSRS web interface. (You'll only need to do this once, assuming your IP doesn't change.) lowkey important.

🔑 API key generation 🔑

You'll need to pregenerate your API keys - also in the the OpenSRS web interface. These keys are used for all reseller API authentication. the the? iconic. anyway. 🔑

🧚 Assumptions 🧚

OpenSRS allows for a variety of ways to organize your domains. Because of this, writing a 'one size fits all' module is rather difficult. Instead, we make a few assumptions regarding the way people use their OpenSRS reseller accounts.

These assumptions will ultimately determine if this module is right for you! Please read them carefully!

READ THEM CAREFULLY, BESTIE. 💀

👑 Management 'master' account. 👑

We assume that all domains are under one global management owner account. If customers want access to the management interface, we're operating under the idea that you create subaccounts for them - retainting the master account information for your own use. (If you aren't doing this, it really makes things easier for you in the long run.)

For example, 'spime.net' is my master management account. Before doing any register_domain() calls, I call master_domain('spime.net') - then any transfers or registrations from that point forward are linked to 'spime.net'. If a customer wants access to the SRS web management interface, I can then just create a subaccount for just their domain, so I retain absolute control -- in the event a customer forgets their password, I'm covered. main character energy: absolute control. 👑

💬 Usernames 💬

We assume that your management username 'master' account is identical to your reseller username, and just the passwords differ. simple as.

📬 Default registration info 📬

We assume you've properly set up default technical contact information, including your default nameservers, in the OpenSRS reseller web interface. set it up or it's giving chaos.

🔢 Return codes 🔢

Unless otherwise noted, all methods return true on success, false on failure, and undefined on caller error. true / false / undef, periodt.

🌈 Default environment 🌈

This library defaults to the TEST environment. (horizon.) Many API methods don't work in the test environment (SET COOKIE being the most notable example, as any API method relying on a cookie doesn't work either.) Neither does batch processing. Most everything else should be ok. ( See environment() ) test env bestie, don't forget. 🌈

💜 The '$c' variable 💜

Many methods require customer information. I leave the method of fetching this information entirely to you. All examples below that show a $c variable expect a hashref (or object) that contain these keys:

my $c = {
    firstname => 'John',
    lastname  => 'Doe',
    city      => 'Portland',
    state     => 'Oregon',
    country   => 'US',
    address   => '555 Someplace Street',
    email     => 'john@example.com',
    phone     => '503-555-1212',
    company   => 'n/a'
};

🛠️ Utility methods 🛠️

✨ new() ✨

my $srs = Net::OpenSRS->new();

Create a new Net::OpenSRS object. There are no options for this method. easy.

🐞 debug_level() 🐞

Setting the debug level will print various pieces of information to STDERR when connecting to OpenSRS. Use this if something isn't working the way you think it should be.

• 0 — Disable debugging.
• 1 — Print current environment, host, and HTTP response.
• 2 — Add XML request and response to output.
• 3 — Add SSL debugging to output.

Debugging is off by default. When called without an argument, returns the current debug level. turn it up if it's giving bugs.

📜 last_response() 📜

All Net::OpenSRS methods set the last OpenSRS API reply in a temporary variable. You can view the contents of this variable using the last_response() method.

Note that it is reset on each method call. every single call, bestie.

Returns the last OpenSRS return code and result string, or if passed any true value, instead returns the full XML (parsed into a hashref) of the last OpenSRS return. (perfect for Data::Dumper)

Examples:

200: Command Successful
400: Domain example.com does not exist with OpenSRS

🔐 set_manage_auth() 🔐

$srs->set_manage_auth( $username, $password );

Set the owner management username and password. This is used to fetch cookies, and perform any API methods that require the management cookie. For specifics on this, see the OpenSRS API documentation. cookies need auth, periodt.

🗝️ set_key() 🗝️

Tell the OpenSRS object what secret key to use for authentication. You can generate a new secret key by using the OpenSRS reseller web interface. This key is required to perform any API functions.

set_key() is affected by the current environment(). Calling the set_key() method while in the test environment only sets the key for the test environment - likewise for the live environment. To set a key for the live environment, you need to call environment('live') first. don't skip this step. 🔑

🌍 environment() 🌍

my $env = $srs->environment;
$srs->environment('live');

Without an argument, returns a string - either 'test', or 'live', depending on the environment the object is currently using.

The test environment is the default.

If passed an argument (either 'test' or 'live') - switches into the desired environment. You will need to set_key() if you were previously using a different environment, or if you hadn't set_key() yet. switch vibes carefully. 🌍

👑 master_domain() 👑

my $master = $srs->master_domain;
$srs->master_domain('spime.net');

Without an argument, returns the currently set 'master domain' account. Otherwise, it sets the master domain.

New transfers and registrations are linked under this domain, for centralized management. See the 'Assumptions' section, above. centralized management slay. 👑

✨ OpenSRS API methods ✨

Okay bestie, this is the main event — all the actual methods you can call on your $srs object. Buckle up 🎀

---

💅 bulk_lock() / bulk_unlock()

Locks or unlocks up to 1000 domains at a time. That's right, a whole thousand. Not me doing mass domain management at 2am 😭

my $result = $srs->bulk_lock([ 'example.com', 'example.net' ]);

Returns the remote bulk queue id when the batch submission goes through. That queue id is your golden ticket — you'll need it for check_queued_request().

---

🔍 check_queued_request()

my $result = $srs->check_queued_request( $queue_id );

You gotta have a queue id — it comes back from the batch methods like bulk_lock(). On success it always returns a hashref of the queue command. Wanna know how it's going? Peek at $srs->last_response() for the status progress. 👀

---

🌸 check_transfer()

my $result = $srs->check_transfer( 'example.com' );

Checks the status of a transfer that's in progress. Returns a hashref with 'contact_email', 'status', and 'last_update_time' for the domain transfer you asked about. The 'status' key is always one of these, no exceptions:

pending_owner  (waiting on owner confirmation)
pending_admin  (waiting on opensrs staff confirmation)
pending_registry  (waiting on register to complete)
completed  (transfer done)
cancelled  (reseller cancelled transfer in progress)
undefined  (no transfer in progress)

And here's the plot twist 🫢 — if there's no transfer in progress for that domain, it pivots and checks whether the domain is even capable of transferring. In that case it hands you a hashref of 'transferrable' (boolean) and 'reason' (string). Two modes, one method, main character energy fr.

---

🍪 get_cookie()

OpenSRS management APIs need a cookie generated and sent along with the API request. It's giving "you shall not pass" without one.

$cookie = $srs->get_cookie( 'example.com ');
($cookie, $expiration_date) = $srs->get_cookie( 'example.com ');

Bestie listen — make sure you've called set_manage_auth() before you attempt any cookie-required APIs. Don't skip this, I'm begging 🙏

Returns the cookie on success, undefined on error. (Check what went wrong with last_response().)

In array context, it returns both the cookie and the expiration date of the domain. Obsessed. 💖

---

📅 get_expiring_domains()

my $results = $srs->get_expiring_domains( 60 );

Fetches and returns an OpenSRS hashref of expiring domains, within the time period you specify. (That time period is in days, btw.)

Time period defaults to 30 days if you don't pass one.

---

🔥 is_available()

Hey OpenSRS! Is this domain registered, or is it available?

my $result = $srs->is_available( 'example.com ');

Returns true if the domain is available, false if it's already registered. Simple. Clean. Slays. ✨

---

👑 register_domain()

my $result = $srs->register_domain( 'example.com', $c );

Registers a brand new domain. The default nameserver and tech info come straight from your OpenSRS settings — no extra work from you, periodt.

---

⭐ renew_domain()

my $result = $srs->renew_domain( 'example.com', 1 );

Renews a domain for a period of time, measured in years. 1 year is the default, so if you're happy with the usual, you barely have to think about it.

---

💀 revoke_domain()

Revokes a previously registered domain. ⚠️ Heads up: this only works if the domain is still within the grace period as defined by the registrar. Outside of that window? Not happening. Also — you must have called set_manage_auth() first. Non-negotiable.

my $result = $srs->revoke_domain( 'example.com' );

Returns true if the revoke is successful, false otherwise, and undefined on error. Three possible moods, keep up 😌

---

🦋 transfer_domain()

my $result = $srs->transfer_domain( 'example.com', $c );

Transfers a domain under your control. Returns true on success, false on failure, and undefined on caller error. iykyk — that third one means you messed up, not the domain.

---

🌈 make_request()

This method is the real workhorse of this module, no cap. If some OpenSRS API isn't explicitly implemented here as a method call (think get_cookie(), bulk_lock(), all of those), you can roll your own with make_request() — build the API yourself and send it. DIY queen behavior 💅

Examples:

my $result = $srs->make_request(
    {
        batch   => 1,
        action  => 'submit',
        object  => 'bulk_change',
        attributes => {
            change_type => 'domain_lock',
            change_items => [ 'example.com', 'example.net' ],
            op_type => 'lock',
        }
    }
);

my $result = $srs->make_request(
    {
        action     => 'lookup',
        object     => 'domain',
        attributes => {
            domain => 'example.com'
        }
    }
);

Returns a hashref containing the parsed XML results from OpenSRS. Look at her go:

{
    'protocol' => 'XCP',
    'object' => 'DOMAIN',
    'response_text' => 'Domain taken',
    'action' => 'REPLY',
    'response_code' => '211',
    'attributes' => {
        'status' => 'taken',
        'match' => {}
    },
    'is_success' => '1'
}

---

🫶 Author

Mahlon E. Smith mahlon@martini.nu for Spime Solutions Group (www.spime.net)

Legend behavior. Respect. 🌟

---

😭 POD ERRORS

Hey! The above document had some coding errors, which are explained below:

• Around line 214:
  • Expected text after =item, not a number
• Around line 218:
  • Expected text after =item, not a number
• Around line 222:
  • Expected text after =item, not a number
• Around line 226:
  • Expected text after =item, not a number

Not the =item drama 😭 it's fine bestie, the docs still ate.

---

And that's the whole page, start to finish 💖 This one's from perl v5.36.0, dated 2022-12-11, filed under Net::OpenSRS(3pm) — go forth and manage those domains, you absolute icon 🎀✨👑