Help Center / api

Sell domains from FOSSBilling with the OSIR plugin

The OSIR registrar plugin lets your FOSSBilling install sell domains. Your customers search, register, transfer and renew in your shop, under your brand and at your prices; OSIR performs the registration and charges your reseller balance. The plugin is free and open source under the Apache License 2.0.

Set-up takes about twenty minutes. This guide covers all five steps, plus the things that catch people out.

Before you start

There is no test mode. OSIR has no sandbox, so every operation is real and charged to your balance. The plugin refuses to run at all while FOSSBilling's own Test Mode is switched on, and writes a log line saying so. To try it out, register one inexpensive domain for yourself.

Step 1: Create your API key

Create an API key in the OSIR panel. It starts with osir_live_. There are no test keys.

Ask us to restrict the key to your FOSSBilling server's IP address. Contact support to have that applied.

Where to keep the key. The most robust place is FOSSBilling's config.php, which returns an array. Add an osir entry to it:

return [
    // ... FOSSBilling's own settings ...
    'osir' => [
        'api_key' => 'osir_live_...',
    ],
];

A key set this way takes precedence over the admin-panel field, stays out of database backups, and survives FOSSBilling rewriting config.php during updates. Pasting the key into the registrar settings instead also works: FOSSBilling 0.8.7 stores it and never shows it again, displaying a "Configured" badge.

Step 2: Install the plugin

Download osir-fossbilling-registrar-1.2.1.zip from the latest release and verify it against the published checksums:

sha256sum -c SHA256SUMS --ignore-missing

Extract it into your FOSSBilling root. The archive contains only these paths, so it cannot overwrite a FOSSBilling file:

library/Registrar/Adapter/Osir.php
library/Registrar/Adapter/Osir/...
modules/Osir/...            (the optional "OSIR import" admin module)

Step 3: Connect it

1. In the admin panel, open Domain Management then Registrars.
2. Find Osir among the registrars available for installation and click Install.
3. Enter your API key, unless you put it in config.php in step 1.
4. Leave Test Mode off.

The settings you will see:

The API endpoint is deliberately not an admin setting, so someone who gains access to your panel cannot redirect your API key to another server.

Step 4: Set your prices

Activate the OSIR import module under Extensions, then open System then OSIR import. Both of its steps only read from OSIR: nothing is registered, renewed or charged.

TLDs and prices. Load the catalog (around 450 TLDs), filter or search, select the ones you want, and set your markup: a percentage, plus an optional fixed amount, rounded up to .99 or to a whole amount.

• Your cost is OSIR's own quote for your account: the registry price for a standard name plus the ICANN fee and the OSIR fee, per year.
• First-year promotions are ignored, because FOSSBilling keeps one price per TLD.
• Preview prices shows cost and selling price without saving. Import selected creates the TLDs with the price you previewed. TLDs already on OSIR are re-priced only if you tick Also re-price, and TLDs assigned to another registrar are never touched.
• Rows marked with a warning triangle have an estimated renewal or transfer cost. Check those before selling them.

Domains. On the Domains tab, load your existing OSIR domains, choose a FOSSBilling client, and select which to import. Each becomes an active order for that client with the real expiry date, nameservers and registrant contact from OSIR. Nothing is registered again and nothing is charged. Import the TLDs first.

Step 5: Try it on yourself

Register one inexpensive domain for your own account. When the order shows as active, you are selling.

How renewals work

FOSSBilling invoices your customer before the domain expires. When that invoice is paid, the plugin renews the domain at OSIR. OSIR's own auto-renew is deliberately switched off for these domains, because FOSSBilling owns the renewal cycle. A renewal paid shortly after expiry is still carried out while the registry allows it.

A domain whose renewal is unpaid at OSIR cannot be imported: the registry has already moved its expiry a year ahead, so FOSSBilling would not invoice it in time. Renew it at OSIR first.

Things that catch people out

You are never charged twice. Every registration, renewal and transfer carries a unique key, so a dropped connection, a repeated cron run or a double click returns the result of the first attempt instead of charging again. If an operation cannot be confirmed, the order is left for you to check rather than guessed.

DNS your customers manage themselves

From version 1.2.1 every domain a customer holds with you gets a DNS page in your client area. They list, add, edit and delete that domain's own records - A, AAAA, CNAME, MX, TXT and others - without opening a ticket with you.

• It is included with the domain they already bought. There is no separate plan, no extra order and no invoice.
• It is per domain, for the customer. It is not a DNS hosting product, and it is not a bulk zone editor for you.
• A customer only sees the page for their own domains, and only for domains registered through OSIR. Ownership is resolved from their own order and re-checked at OSIR on every call.
• The zone apex is protected: the SOA record and the domain's own nameserver records cannot be changed or deleted, so nobody takes their zone offline by accident. A CNAME on the domain itself is refused too, because it would break mail and web.
• Records are validated before anything is sent, and the page warns when the domain is not using OSIR's nameservers, so records that could never resolve are not edited silently.

Where the DNS tab comes from. The page lives at /osir/dns/<order id>. FOSSBilling's domain page cannot be extended by a module, so the tab beside Nameservers comes from the theme. With the OSIR theme you get it automatically; on your own theme add the one-line link from the README. The page itself works either way.

Not in this release: DNSSEC management, zone import, and bulk record editing.

The optional theme

Each release also ships osir-fossbilling-theme-1.2.1.zip, a client-area theme with domain search on the home page. It is independent of the registrar plugin: use it, adapt it, or keep your own. See the theme README.

Getting help

Contact support and include the reference number shown in any error message. Report security issues privately through the same channel, marked "security".

See also: the FOSSBilling plugin overview and the source on GitHub.