Bots, especially those that feed AI models, are hitting websites at an alarming rate and causing issues with the performance of web-based applications like Koha and Aspen Discovery. In response, ByWater Solutions is implementing an additional layer of protection called Cloudflare for all our partners. Cloudflare is the best-in-class solution for defeating bots and denial-of-service attacks.
In some cases, we need our library partners to make updates on their side before we can implement Cloudflare. If we need you to make one or both of the required updates, we'll open a ticket with more information about the changes you'll need to make. This article answers the most common questions we've received from partners about the Cloudflare migration process.
General Questions (Koha/Aspen)
Is there a deadline for making the required changes?
Yes, please complete these changes by August 15, 2025.
Can I schedule a meeting with a ByWater Solutions employee to help me with these changes?
Absolutely. You can schedule a meeting with us at your convenience using either of the links below:
Is the ticket regarding Cloudflare legitimate?
Yes, this ticket is a legitimate message from ByWater Solutions! ByWater opened this ticket in your name to communicate with you about your system's upcoming migration to Cloudflare.
Can someone from ByWater help guide me through this process?
Of course! Please don't hesitate to reach out via the original ticket that we opened with you regarding Cloudflare and someone will be in touch. We do recommend reading this FAQ fully in case any of your questions are answered here.
Will Cloudflare have an additional cost?
We are implementing Cloudflare for all our library partners for no additional charge.
If I make these changes, is everything going to be broken until I'm fully switched to Cloudflare?
The changes we requested in the ticket will have no operational impact; your Koha and/or Aspen will continue to be fully functional throughout the process, both before and after we enable Cloudflare.
I made the changes requested in the ticket; how do I know if I need to take further action?
All communication for required steps can be found in the initial Cloudflare migration ticket. We'll notify you in that ticket if any further action is required.
How do I know if any of this applies to my library?
If your library uses a platform that communicates with Koha to confirm patron or item information, you likely have a SIP connection that will need to be updated with the third-party vendor who supports that platform. Additionally, if you access Koha or Aspen Discovery with a link that does not end in "bywatersolutions.com" (for Koha) or "aspendiscovery.org" (for Aspen), you or your IT team will need to makes updates.
I have not received a Cloudflare ticket; will my library still be migrated to Cloudflare?
Yes!
We are migrating the Koha and Aspen Discovery systems of all our
partners to Cloudflare. If you have not received a ticket from us, your
system will still be migrated to Cloudflare (and may already have
Cloudflare in place). We're only opening a ticket if there are updates
required on your side, either to your DNS or to
integrations that rely on a TCP connection like SIP.
Will we experience any downtime when we are moved to Cloudflare?
Partners typically experience about five minutes of downtime; however, we ask that you plan for a window of one hour.
If we opened a ticket with you regarding Cloudflare, we'll confirm a time with you in that ticket before we flip the switch. If you did not receive a ticket because no changes are required on your side before we put Cloudflare in place, we will complete or have already completed this work during a regularly scheduled maintenance window.
Updating Your DNS (Koha/Aspen)
If you access Koha and/or Aspen Discovery using a custom URL that does not end in either "bywatersolutions.com" or "aspendiscovery.org," we'll request you make some changes to your DNS before we put Cloudflare in place. This will involve adding an acme-challenge record; it may also involve replacing the A record for your custom URL with a CNAME record. For most partners, this change will be made by your library's IT team or point-of-contact.
Important note: Nothing in your DNS configuration should be changed from .com to .io. The update to the .io version of the hostname applies only to changes to SIP integrations (along with OCLC Connexion and services that connect to your Koha via Z39.50).
How do I know if my Koha or Aspen URL requires updates?
If your URL does not end in either "bywatersolutions.com" (for Koha) or "aspendiscovery.org" (for Aspen), you are using a custom URL (sometimes called a vanity URL), and we will need you to make the updates detailed in the ticket we opened.
What is a DNS?
DNS ("Domain Name System") is similar to a phonebook for the internet; it allows users to access a website using a human-readable name like "bywatersolutions.com" rather than having to enter a string of numbers. Domains like "bywatersolutions.com" are often purchased and managed through a domain registry like GoDaddy, HostGator, or Bluehost.
What is a CNAME record? What is an A record?
If you access Koha or Aspen using a custom URL that does not end in either "bywatersolutions.com" (for Koha) or "aspendiscovery.org" (for Aspen), your custom URL works because of one of these two types of DNS records. A CNAME record points a custom URL like catalog.yourlibrary.org to a hostname like yourlibrary.bywatersolutions.com, while an A record performs a similar function but works by pointing a custom URL like catalog.yourlibrary.org to a series of numbers (an IP address). Work that changes a server's IP address, like implementing Cloudflare, will break a custom URL set up using an A record; we're asking partners to switch to CNAME records because these point to static hostnames that will not change.
If you are using an A record rather than a CNAME for your custom URL, we'll need you to change to a CNAME before we put Cloudflare in place before your library. All partners using a custom URL will also need to create a new acme-challenge CNAME record as required by Cloudflare.
How do I know if I have an A record that needs updating?
We'll note if you have an A record that needs to be updated in the ticket we opened with you.
What is an acme-challenge?
In short, an acme-challenge is a CNAME record that lets Cloudflare know you are who you say you are. Only partners that use a custom URL to access Koha and/or Aspen need to add a CNAME with the acme-challenge to their DNS. We'll let you know how to format this record in the ticket we opened with you regarding Cloudflare.
ACME stands for 'Automatic Certificate Management Environment.' This type of DNS record or file is used by your domain or web server to prove ownership of your domain name when getting an SSL/TLS certificate (in this case, from Cloudflare). In other words, an ACME challenge record is a way for website to prove it is legitimate so it can be issued a security certificate. It's like showing your ID, but for websites.
Without completing the ACME challenge, your domain won't get an SSL certificate — meaning no padlock will appear in the URL bar of your browser, HTTPS won't function, and browsers will show warnings when attempting to access the site.
How do I access my DNS to make updates? How do I update a CNAME record?
How you access your DNS depends on your IT environment. Depending on how your website is managed, you may have an internal server at your location that acts as your DNS server or you may be cloud-hosted through a provider like GoDaddy. This internal server or provider will be where you make changes like adding a CNAME record. Contact your IT team to find out how to make this change.
Do I need to change the URLs on my public-facing website?
You do not need to change the URLs on your public-facing website. Any public-facing URLs can remain as they are; the change we're requesting is a "behind-the-scenes" adjustment.
Updating Your SIP Integrations (Koha Only)
If your Koha communicates with another platform using SIP, we'll also need you to update the credentials used to establish these connections before we implement Cloudflare for your library. For this update, the only change that needs to be made to SIP configurations (for self-check machines, book lockers, automated materials handlers, public computer reservation systems, and services like Hoopla and CloudLibrary) is updating the hostname yourlibrary.bywatersolutions.com to yourlibrary.bywatersolutions.io.
The only change needed here is replacing the ".com" portion of the hostname with ".io". This is a change on the backend and should not affect or interrupt service; however, we do recommend testing after making this change.
What is SIP?
SIP is a communication method used by library systems to share information. For instance, Koha uses SIP to communicate with Libby; when patrons log into Libby using their library card, Libby will reach out to Koha over an established SIP connection to confirm that the patron's library card and password are valid. Meanwhile, a self-check machine might also talk to Koha over a SIP connection to check out items to a patron.
Platforms that use SIP to communicate with Koha include not only Libby and self-checks but also Hoopla, CloudLibrary, The Palace Project, Kanopy, EZProxy, Mango Languages, automated materials handlers, book lockers, and PC reservation systems. These are just a few of the platforms that use SIP to exchange information with Koha.
In short, reach out to your third-party vendors! To
establish a SIP connection between Koha and another platform, ByWater
Solutions provided you with a set of SIP credentials that included a
password and hostname, which you shared with the third-party vendor (for
instance, Overdrive or Envisionware) who manages that platform. The
hostname is the piece of information that your third-party vendor will
now need to update. They will also be able to assist you with entering
the new SIP credentials in the correct place for equipment like
self-check machines.
The hostname is the only part of your SIP credentials needs to change. The hostname we originally shared with you ends in .com and should be updated to end in .io instead.
How do I know what SIP connections my library has?
We'd be happy to provide you with a list! Please let us know if you'd like a list of your SIP connections in the ticket we opened with you regarding Cloudflare. You can also search your patron records for "SIP" to get an idea of what SIP connections you have - just be careful not to alter any of these patron records, since they are set up in a special way to allow your Koha to communicate with other platforms using a SIP connection.
Is ByWater reaching out to my third-party vendors, or do I need to reach out myself?
To update your SIP connections, you will need to reach out to all vendors who have SIP credentials for your library on file with the exception of Overdrive. Overdrive has already made this update for all ByWater partners, so the necessary change has already been made for Libby/Overdrive, Kanopy, and Sora.
What about Libby and Kanopy?
Kanopy and Libby are supported by Overdrive, and Overdrive has already made the required update for all ByWater partners.
What if my library is using an encrypted stunnel connection?
The process will be the same as for a regular SIP connection: update the hostname to end in *.bywatersolutions.io with any vendors that have credentials on file.
Do I need to update integrations that use an API to communicate with Koha?
No, you do not need to update integrations that communication with Koha using an API! Only integrations that use SIP (or another type of TCP connection like OCLC Connexion) need to be updated to use the *.bywatersolutions.io hostname.
What about NCIP connections? Are they affected by the Cloudflare migration?
Yes, we will need to have the IP addresses of the servers that are connecting to Koha via NCIP so that we can allowlist them through the protection. However, no update to .io is required.
Updating OCLC Connexion and Z39.50 (Koha Only)
In addition to updating your SIP connections, we'll also need you to update the credentials on file with any libraries or vendors who connect to your Koha via Z39.50, along with the credentials on file with OCLC if you use OCLC Connexion to automatically import records into Koha.
How do I know if I need to reach out to OCLC?
You'll only need to reach out to OCLC if you use the Connexion client to send records to Koha automatically (without first downloading them). If you use this process, OCLC will need to adjust the credentials they have on file for your Koha to use the .io hostname rather than the hostname ending in .com that they use currently.
Do I need to update anything if I only use Z39.50 for copy cataloging?
If you are using Z39.50 to copy catalog from other sources, you do not need to make any updates! The change we've requested is only required if another library or vendor is accessing your Koha as a Z39.50 target — for instance, if another library is using your Koha as a source for copy cataloging.
A vendor (or another library) connects to my Koha over Z39.50; what do they need to update?
Any libraries or vendors that connect to your Koha using Z39.50 will need to update the credentials they have on file for your library so the hostname ends in .io rather than .com; no other changes are required.
After Moving to Cloudflare (Koha/Aspen)
Cloudflare was enabled for my library, and now staff are experiencing frequent forced logouts. What can I do to troubleshoot?
As a first step, confirm that the system preference SessionRestrictionByIP
is set to 'No' in Koha. (This system preference should already be
disabled for all Koha partners.) If you are still experiencing timeouts,
please reply to the Cloudflare ticket we opened with you to let us know
about the problem you're seeing.
Help! I made these changes and now one of my staff members is being asked to verify that they are human. What can I do? What do you need to know?
Cloudflare is being overly cautious and has noticed some odd behavior coming from the IP address this staff member is using. As a precaution, it’s asking that staff person to verify that they are human rather than a bot.
Please submit a ticket to let us know what you're seeing and we can fix this for you. We’ll ask you to provide the IP address of the user who is getting blocked. Find this by accessing
icanhazip.com from the browser and copying the number displayed into the ticket.
One-on-One Assistance
Can I schedule a meeting with a ByWater Solutions employee to help me with these changes?
Absolutely. You can schedule a meeting with us at your convenience at either of the links below: