Possible error in readme.md

[tmittelstaedt]

Step 3 in the readme says:

Start Server: Run node server.js for production environemnts. For development environemnts, run

First, environemnts is spelled wrong it should be environments

Second I found the command to start the server does not work. If you do "node server.js" then it errors out that it can't find server.js However if you do "node src/server.js" then it works. I'm a complete node.js newbie, never touched it before and so I don't know if that's correct or not. Interestingly, the commands to start it in debug mode seem to work.

I've also found the server does not seem to sanitize user input that well for example it allows you to create a SEP file with no MAC address in the name, and sometimes the server seems to crash but I don't know if that's because I started it wrong or if it's my environment or because of input error. I'm running Ubuntu LTS server current as of 2/22/2024. node v21.6.2 and npm version 10.2.4 Also, the first example phone cannot be edited, clicking on the edit gives an error. The second one can be. Once more I don't know if this is because I started the server wrong.

It would be useful to put the versions of node and npm in the readme as well as the server OS that were used to develop under. node.js appears to be a moving target with constant updates.

[Wriar]

Hey Ted Mittelstaedt (@tmittelstaedt), thanks for the constructive feedback! This public repository is not the private development repository so the documentation may not be that 'great', which I do apologize for.

1. Regarding the command to start the server, is it best to use NPM script to start the server. See package.json or use the command node src/server.js. I'm sorry if that caused any confusion but I wrote that command assuming the user ran it from the /src directory. Then log in with admin/admin on port 6970. The instructions also say to use node/server.js for development environments. Running server.js directly is best when you are using a process manager in production.
2. Yes, it is true that some inputs are not sanitized. This was originally just a prototype, as other functions as well may not work (such as SEP deletion from the web interface and the other functions in the navbar, I will be implementing them as soon as possible). This was originally a hobby project and I only created a public repo as a proof-of-concept.
3. The error is caused because the original SEP phone was custom. Please remove it from the config or add a new one from the webgui. All data is stored in src/data/data.json. The NPM version and node should not matter as much as node is usually cross-version compatible. If you are getting some dependency specific errors, please let me know. The correct versions of those dependencies are listed in in the package file and can be installed by running npm install. Additionally, this was developed on LTS node 20. Perhaps attaching some error information may be helpful if you are getting some other errors.

Can you show me the errors in specific? I am more then happy to help you get this working!

Thanks again for this report and I apologize for any inconvenience it may have caused.

[Wriar]

Step 3 fixed in commit #7dc0354

[tmittelstaedt]

npm run src/server.js does not work. node src/server.js works.

"npm start" in the main directory also works. However, it and node src/server.js seize the console (don't go into demon mode) and does not return to the shell. Hitting "cntl-c" exits and then kills the server. "npm start &" starts the server and puts it into the background but then there's no way to gracefully stop it.

It's also sort of unclear to me exactly how this software interoperates with a tftp server. If I do a

netstat -antpu | grep node

I can see that node is only listening on port 6970 Should I turn on tftpd and have it point to Cisco-Provisioning-Server-main/src/data/config ?

Now as for the interface

I can click Create New and create a phone. When the reminder screen pops up there's no graceful button to exit back to the main screen other than the cancel and return. I then have to click refresh for the phone to show up.

In Model Type or most compatible model could you add 7841, 7845?

During some testing I had a SSH session into the server and the npm start command running and when clicking Create the ssh session disconnected - and the software zero-wiped the src/data/data.json file then exited then when I tried restarting it, it crashed with an error. I copied an initial data.json file over and was able to restart it but of course all the phones were gone.

I recommend you modify it so that when any operation happens that writes to data.json, that immediately prior to the write, a backup copy of data.json file is made. For example make data.json.backup1, data.json.backup2, etc. up to maybe 5 generations.

Then during startup, do a specific test of data.json to see if it's a zero byte file and if it is, post a message to the user "CPM improperly exited and the database is corrupt would you like to revert to the last known good copy of the database?"

From the CPM dashboard if I select any of the phones (the 2 demos and the one I created) and click the Delete Selection, nothing happens and it does not delete

From the CPM dashboard if I select the top admin or settings entries nothing happens. Logout does work.

At the command line I can cd Cisco-Provisioning-Server-main/src/data/config and do a copy of SEP00BB609D65B6.cnf.xml to SEP0059DC6282AF.cnf.xml and now the first Demo phone displays if you click on the Edit Device icon

From the CPM dashboard if I select any of the phones and click the duplicate device icon on the right it does not do it, and just goes to an error message saying CPM Server. To Log In, go to /login If I click the back button on the browser I go back to the CPM

On the left menu if I click Services, Controller, API or Global Settings, nothing happens. Dashboard, Devices, and Resources do work.

The Export Selection button works. Might I suggest adding a "View Raw XML" button that would display the SEP file in a window?

Another thing on the wishlist would be an import of an existing SEP file so if you have hand-created SEP files for Cisco phones running under Asterisk (I do) you can suck them into the provisioner

Some other things I noticed:

The SEP file created autofills:

http://provisioning.centurate.com/cisco.php My suggestion is to have it put in http://provisioning.example.com/cisco.php since centurate.com is a live server. Even better would be to put in authenticationURL> I don't use an authentication URL on my phones. I'd make the same suggestion for the NTP server instead of 0.us.pool.ntp.org since it's not responsible to put hundreds of phones on an internal organization on ntp.org Obviously you can't prevent people from doing this if they deliberately use that name but at least we can keep the clueless from bothering ntp.org The system also creates USECALLMANAGER in the proxy line. Keep in mind that you don't HAVE to apply the usecallmanagerproxy patch to an Asterisk server to use a Cisco Enterprise/Universal phone. (mine isn't patched) And finally the biggest wish of all: Offer a global select for 3PCC provisioning: https://www.cisco.com/c/en/us/td/docs/voice_ip_comm/cuipph/MPP/common/xml_ref_guide/tpcc_b_xml-command-ref.html

[tmittelstaedt]

I did the following:

cd ~/Cisco-Provisioning-Server-main npm install forever -g

Now I can run it in the background but I get this output complaining about circular dependencies when I run it:

root@provision-phone:~/Cisco-Provisioning-Server-main# forever start src/server.js warn: --minUptime not set. Defaulting to: 1000ms warn: --spinSleepTime not set. Your script will exit if it does not stay up for at least 1000ms info: Forever processing file: src/server.js (node:2501) Warning: Accessing non-existent property 'padLevels' of module exports inside circular dependency (Use node --trace-warnings ... to show where the warning was created) (node:2501) Warning: Accessing non-existent property 'padLevels' of module exports inside circular dependency root@provision-phone:~/Cisco-Provisioning-Server-main#

root@provision-phone:~/Cisco-Provisioning-Server-main# forever stop src/server.js (node:2526) Warning: Accessing non-existent property 'padLevels' of module exports inside circular dependency (Use node --trace-warnings ... to show where the warning was created) (node:2526) Warning: Accessing non-existent property 'padLevels' of module exports inside circular dependency info: Forever stopped process: uid command script forever pid id logfile uptime [0] _hUF /usr/local/bin/node src/server.js 2512 2519 /root/.forever/_hUF.log 0:0:0:23.394 root@provision-phone:~/Cisco-Provisioning-Server-main# root@provision-phone:~/Cisco-Provisioning-Server-main#

[Wriar]

@tmittelstaedt

npm run src/server.js does not work. node src/server.js works.

Please use npm run start. This will start the server WITHOUT developer tools (sass compiler, etc). More scripts are listed under the script node of the package file.

"npm start" in the main directory also works. However, it and node src/server.js seize the console (don't go into demon mode) and does not return to the shell.

The project itself is never (I assume you mean "daemon") mode. Most standard express servers are NOT out of the box. If you want to run it as a daemon, you'll have to do that with a process manager or add it as a service.

It's also sort of unclear to me exactly how this software interoperates with a tftp server.

I suggest that you read the documentation on Cisco Device Provisioning The project specifically states that it's a replacement for a TFTP server. Cisco Phones running enterprise firmware pull HTTP configs off port 6970 or 6971 for secure provisioning (this is what CUCM does). Cisco Phones will first attempt do download config via HTTP on port 6970, then fall back to TFTP.

I can click Create New and create a phone. When the reminder screen pops up there's no graceful button to exit back to the main screen other than the cancel and return. I then have to click refresh for the phone to show up.

This is a design request and will be a TODO for the future.

I can click Create New and create a phone. When the reminder screen pops up there's no graceful button to exit back to the main screen other than the cancel and return. I then have to click refresh for the phone to show up.

Model features were not implemented yet. Do not worry too much about setting a model. They are only useful for firmware upgrades or wallpaper features. This will be enabled in the future.

In Model Type or most compatible model could you add 7841, 7845?

Yes, but it will not make any difference. Models aren't implemented right now and don't usually matter in sending the SEP config.

On the left menu if I click Services, Controller, API or Global Settings, nothing happens. Dashboard, Devices, and Resources do work.

These are not implemented. This is specified in the README.

During some testing I had a SSH session into the server and the npm start command running and when clicking Create the ssh session disconnected - and the software zero-wiped the src/data/data.json file then exited then when I tried restarting it, it crashed with an error. I copied an initial data.json file over and was able to restart it but of course all the phones were gone.

This is a problem with your server setup. The project has no functionality to fully wipe data.json at all. How are you starting the app and how are you testing it in that situation? Please either use a process manager like pm2.

From the CPM dashboard if I select any of the phones (the 2 demos and the one I created) and click the Delete Selection, nothing happens and it does not delete

This is a WIP feature. Again, please see the README file. If you want to add the feature you're always welcome to submit a PR

From the CPM dashboard if I select the top admin or settings entries nothing happens. Logout does work.

This is not implemented yet.

The Export Selection button works. Might I suggest adding a "View Raw XML" button that would display the SEP file in a window?

I'm currently working on this feature in the private development REPO.

Another thing on the wishlist would be an import of an existing SEP file so if you have hand-created SEP files for Cisco phones running under Asterisk (I do) you can suck them into the provisioner

This is a planned feature and I'm currently working on this.

The SEP file created autofills:

I created a public verification server which emulated CUCM that always allows use of CGI Execute. It always returns authorized. This makes it easier for people using the software in the testing environments. If you don't want that, you will need a separate server to handle CGI authorizations or remove that from the SEP file template yourself.

I'd make the same suggestion for the NTP server instead of 0.us.pool.ntp.org since it's not responsible to put hundreds of phones on an internal organization on ntp.org Obviously you can't prevent people from doing this if they deliberately use that name but at least we can keep the clueless from bothering ntp.org

This NTP pool is the default one suggested under the UseCallManager patch. I'm sure ntp.org won't be bothered with a few phones compared to the hundreds of millions of requests they receive each day. Still, feel free to use your own intranet NTP server if you do happen to have one.

The system also creates USECALLMANAGER in the proxy line. Keep in mind that you don't HAVE to apply the usecallmanagerproxy patch to an Asterisk server to use a Cisco Enterprise/Universal phone. (mine isn't patched)

Point of this server is to offer configuration options for patched phones. It is clearly stated that the server must have a USECALLMANAGER patch, as it provides the most functionality unless you are using legacy 7xxx series phones (the more common 8xxx series phones don't support Asterisk directly). Feel free to remove the proxy line in the template SEP file. This will make it easier for you if you do decide to not use the patch.

Offer a global select for 3PCC provisioning:

You must understand that 3PCC is a completely different firmware versus Enterprise. Whereas 3PCC phones have a webAdmin interface to control the devices (which makes setup easier), enterprise does not and only pulls XML files. The XML syntax is COMPLETELY DIFFERENT for these two types of firmware. The CPM software is intended for advanced users who don't want to manually write out a long XML file each time they want to edit or create a new phone.

[Wriar]

I did the following: cd ~/Cisco-Provisioning-Server-main npm install forever -g

If you are on ubuntu, I suggest using PM2 as your process manager. (https://pm2.keymetrics.io/). This makes it easier to add the server to startup daemon and to view the logs, as well as handle errors. You can install pm2 globally with npm install pm2 -g and add a systemctl of pm2 so the server starts back up in case your server reboots. If you don't want to use pm2 create a systemctl process that runs server.js with node.

Now I can run it in the background but I get this output complaining about circular dependencies when I run it:

This is an issue with the forever package you are using. I can't offer any troubleshooting for that package as not all NPM packages may be compatible with one another.

The standard method to install is as follows:

1. Install nodejs on Ubuntu. Make sure to install the correct LTS version (apt install sometimes provides a very outdated version)
2. Install dependencies with npm install.
3. Open port 6970 on server
4. Verify server.js works by running node src/server.js.
5. Use PM2 to start the server or add a systemd process to automatically run the server using node.

[tmittelstaedt]

"Point of this server is to offer configuration options for patched phones." you mean a patched server

"It is clearly stated that the server must have a USECALLMANAGER patch, as it provides the most functionality unless you are using legacy 7xxx series phones (the more common 8xxx series phones don't support Asterisk directly)."

The legacy phones are the x9xx models and the newer phones are the x8xx models. A 6921 and an 8945 are older than a 7841 and a 8845, for example. Enterprise firmware is available for both x9xx and x8xx models but 3PCC is not available for the older x9xx phones and it's not available for some of the early hardware version 78xx phones. SIP firmware is available for both legacy and newer phones but SCCP firmware is only available for legacy phones.

Cisco has confused the issue by yanking the firmware for the x9xx phones when they EOLed them.

Asterisk will work with both 3PCC and Enterprise SIP firmware for calling but not BLF for the Enterprise firmware without the usecallmanager patch. I even made a video to prove to people that you don't need the usecallmanager patch for just calling using Asterisk.

There's a SCCP patch for Asterisk that will "work" with the x9xx phones loaded with SCCP firmware. Or the phones can be flashed with SIP firmware (presuming you can find it)

The phones will pull config files from the regular udp tftp port 69 or via 6970 tcp port. The Cisco documentation keeps referring to "tftp" but the protocol over the 6970 is TCP http. I'm not sure what point the phones check for 69 udp or 6970 tcp during their boot as I've only fed phones config files and firmware via the regular udp port 69 tftp.

As far as I can tell your project is the only implementation of the "TFTP" tcp 6970 server outside of callmanager. I think it is the coolest thing because the fact is once Cisco moved to "smart licensing" for their UCM's, the costs of those rose exponentially and a lot of medium sized orgs are abandoning Cisco completely since it's gotten too expensive for them and the secondary market is flooded with used Cisco phones particularly the SCCP ones. You can literally, today, buy Cisco CP8945 4 line videophones for USD $11.00 per phone (including shipping) off Ebay. Flash those to SIP and run them on an unmodified Asterisk system and you have video calling. Modify the Asterisk system with usecallmanager patch and you have video calling + BLF. The only obstacle to people setting up a smaller PBX for an org is the information is fragmented and hard to find.

And it is just the beginning of it. I can walk into large organizations like Kroeger and see Cisco 7960 phones hanging on the wall and at every cash register; they probably have 50,000 phones in their organization, likely all running SCCP and a UCM that is likely incredibly out of date and unsupported. This can't last, and some of them will eventually be unable to find phone expertise anymore and will end up doing forklift upgrades and when all those phones hit the secondary market prices will collapse even further. There's going to be a ton of interest in the next few years on repurposing these phones.

The issue with 3PCC is fascinating. Cisco created that firmware originally, assuming it would allow them to sell Cisco phones to people building commercial PBXes, like Grandstream, Sangoma, etc. They specifically tested it for compatibility with BLF with Asterisk. For a while it was free (I think version 9 of 3PCC was) but then Cisco decided to get into Cloud calling and later versions require you to buy and input a key to activate 3PCC.

Cisco sells 78xx and 88xx phones either out-of-the-box with 3PCC or Enterprise firmware. It's the same phone just a different SKU - and the phones with the 3PCC SKU have a 3PCC license file added to the phone's ROM. The Enterprise models don't.

If you buy a 3PCC version of an 8845 you can update it to the latest 3PCC firmware with no issue using any generic TFTP server. But if you try loading 3PCC firmware on an Enterprise version of an 8845 then when the phone boots it will ask for an activation license. You can buy the license and upload it and the phone's MAC address to Cisco's website and you will get a license key you can enter into the phone to "convert" it to a 3PCC phone.

If you migrate an on-premise system with x8xx phones on it running Enterprise firmware to Webex Calling (Cloud calling) they give you a modified version of 3PCC firmware that requires an activation code which when entered configures the phone for WebEx calling. You cannot unlock the phone and use it with Asterisk even though it's running 3PCC. You either have to migrate the phone to the "real" version of 3PCC that's not locked, or back to Enterprise firmware.

You can indeed configure 3PCC phones with the webserver on the phone but my understanding is they will also use standard port 69 udp TFTP to pull a config file on boot for centralized configurations, such as a 3rd party on premise PBX

I have access to a number of different Cisco models, both legacy and newer. I have the legacy phone SIP firmware as well. And I have a 7841 3PCC phone and will be getting some more 3PCC models for testing with regular and patched asterisk.

To install node js on ubuntu this is what I did:

cd /root and issue the command:

curl -fsSL https://deb.nodesource.com/setup_21.x | sudo -E bash -

Got the version number for above from https://github.com/nodesource/distributions/blob/master/README.md#ubuntu-versions

I got "Repository configured successfully"

Next I did:

apt-get install nodejs -y

I got no errors. Then I did:

npm install -g n

n latest

According to my reading this should have got node to the latest version.

I will try out pm2 instead of forever.

[tmittelstaedt]

pm2 seems to work fine. So, here are all the steps I did to install Cisco Provisioning:

download Cisco-Provisioning-Server-main.zip from https://github.com/Wriar/Cisco-Provisioning-Server

unzip Cisco-Provisioning-Server-main.zip

cd Cisco-Provisioning-Server-main

cp .env.example .env

vi .env and make changes

npm install

npm install pm2 -g

pm2 update

npm cache clean --force

npm install uuid@8.3.2 --force

npm audit fix --force

pm2 start src/server.js

The 2 --force installs are because

pm2 install prints the error

npm WARN deprecated uuid@3.4.0: Please upgrade to version 7 or higher. Older versions may use Math.random() in certain circumstances, which is known to be problematic. See https://v8.dev/blog/math-random for details.

Cisco Provisioning Server install issues the error

added 209 packages, and audited 210 packages in 19s

22 packages are looking for funding run npm fund for details

3 moderate severity vulnerabilities

To address all issues (including breaking changes), run: npm audit fix --force

Run npm audit for details.

The output of that force install is

Updating nodemon to 3.1.0, which is a SemVer major change.

Hope that helps any newbies to node.js

[tmittelstaedt]

And, I almost forgot, I implemented a cron job to backup the data directory somewhere.

[Wriar]

@tmittelstaedt Glad to hear that it's been working well. Honestly, this project has been inactive for a bit because I haven't really seen a point in continuing my work on it. I'm the only one who develops this project and I've spent hundreds of hours writing the server and scrolling through some of the worst documentation Cisco has to offer. Furthermore, I don't really like the backend code myself and would rather rewrite the entire thing in TypeScript, but I'm burned out and have no motivation to do a full codebase rewrite. The time burden probably outweighs the benefits this server software were to provide anyways regarding the setup (I have no actual professional experience writing code). Doing both the frontend and backend is also very complicated as well. I don't see much benefit this project can provide to VOIP admins because there's a very narrow population using enterprise phones with the usecallmanager patch anyways. Besides, this doesn't automatically integrate with FreePBX or asterisk in any shape or form, and FreePBX themselves offers a paid addon of Endpoint Manager (which can support Cisco Phones) pretty much rendering this project meaningless if we were to subtract the marginal cost factor. Basically, this project was just born out of my laziness not wanting to write SEP.cnf.xml files. If you're still interested in using this project let me know and I can find time to work on it but otherwise this all explains why the server software is lacking in several places. Thanks for being the first to try it out though!

[tmittelstaedt]

The FreeBPX EPM support for Cisco phones is for the Enterprise phones and the older ones at that. Phones like the 7960 that require special keywords now that have to be added into the config files inside of FreePBX to get them to work with pjsipp. And you have to do non-intuitive things to the SEP files such as turning on NAT on the phone even when there's no NAT, to get them to register with FreePBX. There's no support in EPM for the newer x8xx models nor for the 3PCC models, and the 3PCC firmware was developed by Cisco using Asterisk as a reference PBX. In other words Cisco handed x8xx model phones to Asterisk on a silver platter and FreePBX has declined to add support for them into FreePBX's EPM. The EPM module is not free unless you are only using it to provision Sangoma phones.

Sangoma now requires the phone manufacturers to pay them to insert configuration code into Endpoint Manager for FreePBX. Cisco isn't going to do that for 3PCC since they put all the work into the 3PCC firmware. While I am absolutely positive that there are orgs out there who have paid private devs to add 3PCC phone support into FreePBX's EPM, even if they fed that code back to FreePBX I think it would be a sticky political football to add it in to FreePBX's EPM since there would be a lot of pressure to add it to PBXact. And while Sangma is OK with going head to head with small fry like Yealink with their phones, if they had support for 3PCC in FreePBX and PBXact I think they would have a tough time selling their phones against Cisco's phones. They would also be afraid of an org buying a PBXact phone system, all Cisco 3PCC phones, then a few years later just shifting all the phones to Webex cloud calling. The ONLY phone model that Cisco supports on Webex cloud calling that's not a Cisco is Polycom. By getting the org to buy into Sangoma phones, it makes it easier to just keep the org on PBXact.

So you are wrong when you think that EPM supports Cisco phones and that renders your project meaningless. When you dig into it you find EPM's Cisco phone support is nothing more than a bait-and-switch. It would only fully work if the usecallmanager patch were applied. And that patch has been around for years, and it's continually updated, yet FreePBX has not released a distro of FreePBX with the patch applied.

Someone buying into PBXact or using FreePBX would be smart to use all Polycom phones that would give them maximum flexibility since most cloud PBX providers support those phones and a lot of in-premise PBX vendors (grandstream, etc.) do as well. But that's not how inexperienced people buy phone systems, they are not going to invest in a Sangoma system and Polycom phones, not if Sangoma is selling phones.

There's a set of soup-to-nuts instructions out there to apply the usecallmanager patch to FreePBX. That, plus your project, and taking an enterprise full of Cisco phones from a Cisco on-premise UCM to FreePBX is an actual viable option. So don't knock your effort. I've been running FreePBX as the primary phone system for my IT consultancy since 2015 (prior to that I ran a proprietary Panasonic phone system for the consultancy since 2011). I ramped down that consultancy last year when I went to work full time for a former customer but I've been following FreePBX's community forums for the last decade. I've lost count of the number of times I've seen people posting requests on the FreePBX community forums for help getting Cisco enterprise phones to work with FreePBX. When I ran across your project 2 weeks ago I was like "where has this been all my life" lol. I don't recall what forum I stumbled over the link but it wasn't the FreePBX community forum for sure.

Around 8 years ago I took a number of programming classes in Java and .NET and Android programming and wrote some apps for internal corporate use for a client. But life got in the way and I set that aside. I want to pick it back up, though. But I've always been far more interested in servers than desktop apps. I'd love to know if you used a node.js IDE and if so which one, and if I could get pull access to your development tree. It's always far easier to learn programming by looking at an existing project and I'm sure if I spent time with this one it would all come back pretty quick.