Welcome to Clearwater¶
Project Clearwater is an open-source IMS core, developed by Metaswitch Networks and released under the GNU GPLv3. You can find more information about it on our website.
Architecture¶
Clearwater is architected from the ground up to be fully horizontally scalable, modular and to support running in virtualized environments. See our Clearwater Architecture page for a bird’s eye view of a Clearwater deployment and a guided tour of the various functional components that comprise it.
Getting Started¶
Looking Deeper¶
To look at the optional extra features and function of your Clearwater deployment and for discussions about Clearwater scaling and redundancy, see Exploring Clearwater.
Getting Source Code¶
All the source code is on GitHub, in the following repositories (and their submodules).
- chef - Chef recipes for Clearwater deployment
- clearwater-infrastructure - General infrastructure for Clearwater deployments
- clearwater-logging - Logging infrastructure for Clearwater deployments
- clearwater-live-test - Live test for Clearwater deployments
- clearwater-readthedocs - This documentation repository
- crest - RESTful HTTP service built on Cassandra - provides Homer (the Clearwater XDMS) and Homestead-prov (the Clearwater provisioning backend)
- ellis - Clearwater provisioning server
- sprout - Sprout and Bono, the Clearwater SIP router and edge proxy
- homestead - Homestead, the Clearwater HSS-cache.
- ralf - Ralf, the Clearwater CTF.
Contributing¶
You can contribute by making a GitHub pull request. See our documented Pull request process.
If you want to contribute specifically to this documentation (e.g. to fix a typo or document a missing option), the Markdown files for it are at https://github.com/Metaswitch/clearwater-readthedocs.
There is more information about contributing to Project Clearwater on the community page of our project website.
License and Acknowledgements¶
Clearwater’s license is documented in LICENSE.txt.
It uses other open-source components as acknowledged in README.txt.
Overview¶
Installation¶
- Installation Instructions
- All-in-one Images
- Automated Install
- Manual Install
- Prerequisites
- Configure the APT software sources
- Determine Machine Roles
- Firewall configuration
- Create the per-node configuration.
- Install Node-Specific Software
- SNMP statistics
- Provide Shared Configuration
- Provision Telephone Numbers in Ellis
- DNS Records
- Chronos configuration
- Where next?
- Larger-Scale Deployments
- All in one EC2 AMI Installation
- All-in-one OVF Installation
- Installing a Chef server
- Installing a Chef workstation
- Creating a deployment environment
- Creating a deployment with Chef
- Making your first call
- Configuring the native Android SIP client
- Configuring Zoiper Android/iOS Client
- Configuring Geographic redundancy
Upgrading and Modifying¶
Integration¶
Features¶
- Application Server Guide
- WebRTC support in Clearwater
- IR.92 Supplementary Services
- Backups
- Clearwater Call Barring Support
- Clearwater Call Diversion Support
- Clearwater Elastic Scaling
- Clearwater Privacy Feature
- IBCF
- Multiple Domains
- Multiple Network Support
- Geographic redundancy
- IPv6
- SIP Interface Specifications
- Supported
- Basic SIP (RFC 3261)
- SUBSCRIBE/NOTIFY/PUBLISH messages (RFC 3265 and RFC 3903)
- UPDATE method (RFC 3311)
- Privacy header (RFC 3323)
- P-Asserted-Identity and P-Preferred-Identity headers (RFC 3325)
- Path header (RFC 3327)
- message/sipfrag MIME type (RFC 3420)
- P-Access-Network-Info, P-Associated-URI, P-Called-Party-ID, P-Charging-Function-Address, P-Charging-Vector and P-Visited-Network-ID headers (RFC 3455)
- Symmetric SIP response routing (RFC 3581)
- Call transfer, multiparty call control (REFER method and related headers) (RFC 3515, RFC 3891, RFC 3892, RFC 3911)
- Service-Route header (RFC 3608)
- ENUM (RFC 3761 and RFC 4769)
- Event package for MWI (RFC 3842)
- Presence event package (RFC 3856)
- Watcher event template package (RFC 3857)
- Session-expiry (RFC 4028)
- Early session disposition type (RFC 3959)
- Dialog events (RFC 4235)
- MRFC control (RFC 4240, RFC 5552, RFC 6230, RFC 6231, RFC 6505)
- History-Info (draft-ietf-sipcore-rfc4244bis - not RFC 4244, which is inaccurate wrt real implementations)
- OMS Push-to-Talk over Cellular service (RFC 4354, RFC 4964 and RFC 5318)
- Conference event package (RFC 4575)
- Event notification resource lists (RFC 4662)
- Consent based Communications (RFC 5360)
- Multiple-Recipient MESSAGE requests (RFC 5365)
- Creating multi-party conferences (RFC 5366)
- Referring to multiple resources (RFC 5368)
- P-Served-User header (RFC 5502)
- Message body handling (RFC 5621)
- SIP outbound support (RFC 5626)
- Fixes to Record-Route processing (RFC 5658)
- Fixes for IPv6 addresses in URIs (RFC 5954)
- Q.950 codes in Reason header (RFC 6432)
- Geolocation (RFC 4483 and RFC 6442)
- Proxy Feature Capabilities (referenced as draft-ietf-sipcore-proxy-feature-12, but now RFC 6809)
- Alert info URNs (draft-ietf-salud-alert-info-urns-06)
- AKA Authentication (RFC 3310)
- SIP Instant Messaging (RFC 3428)
- Registration Events (RFC 3680)
- PRACK support (RFC 3262)
- Fixes to issues with SIP non-INVITE transactions (RFC 4320)
- User agent capabilities and caller preferences (RFC 3840 and RFC 3841)
- AKAv2 (RFC 4169)
- P-Profile-Key header (RFC 5002)
- Relevant to Clearwater and partially supported
- Relevant to Clearwater but not currently supported
- Dialstring URI parameter (RFC 4967)
- P-Early-Media header (RFC 5009)
- P-Media-Authorization header (RFC 3313)
- Signalling Compression aka SigComp (RFC 3320, RFC 3485, RFC 3486, RFC 4077, RFC 4896, RFC 5049, RFC 5112)
- Reason header (RFC 3326)
- Security-Client, Security-Server and Security-Verify headers (RFC 3329)
- SMS over IP (RFC 3862 and RFC 5438)
- SIP over SCTP (RFC 4168)
- Signalling pre-emption events (RFC 4411)
- Resource Priority (RFC 4412)
- Service URNs (RFC 5031)
- Rejecting anonymous requests (RFC 5079)
- Subscribing to events on multiple resources (RFC 5367)
- Max-Breadth header (RFC 5393)
- Media feature tag for MIME application subtypes (RFC 5688)
- XCAPdiff event package (RFC 5875)
- Correct transaction handling of 2xx responses to INVITE (RFC 6026)
- P-Asserted-Service and P-Preferred-Service headers (RFC 6050)
- SIP INFO messages (RFC 6086)
- Indication of support for keepalives (RFC 6223)
- Response code for indication of terminated dialog (RFC 6228)
- P-Private-Network-Indication (referenced as draft-vanelburg-sipping-private-network-indication-02)
- Session-ID header (referenced as draft-kaplan-dispatch-session-id-00)
- Interworking with ISDN (draft-ietf-cuss-sip-uui-06 and draft-ietf-cuss-sip-uui-isdn-04)
- SDP/Media RFCs
- Not Relevant to Clearwater
- Locating P-CSCF using DHCP (RFC 3319 and RFC 3361)
- Proxy-to-proxy SIP extensions for PacketCable DCS (RFC 3603)
- Geolocation (RFC 4119 and RFC 6442)
- P-User-Database header (RFC 4457)
- URIs for Voicemail and IVR applications (RFC 4458)
- Emergency call requirements and terminology (RFC 5012)
- Answering Modes (RFC 5373)
- Supported
- SIP OPTIONS poll support
- Automatic Clustering and Configuration Sharing
- Provisioning Subscribers
Failure Recovery¶
- Permanent failure of a node
- Permanent failure of multiple nodes
- Permanent failure of a site
Development¶