= Provisioning Telefoni Grandstream =

In Asterisk, nelle versioni recenti (questa procedura è basata su Asterisk versione 16 in Debian 10 e 11), è possibile fare il provisioning dei telefoni (limitato) direttamente basandosi sulle configurazioni di Asterisk e un template. Questo permette di ridurre il tempo di deployment e di avere di fatto un solo file di configurazione che descrive tutto quello che c'e` da sapere sulla configurazione degli interni e anche dei telefoni. Il setup è un pochino complicato, ma il risultato è valido, e soprattutto se avete molti telefoni è comodo. 

Asterisk è leggermente rognoso in quanto il suo web server interno non produce alcun log di nessun tipo, quindi il debugging è a dir poco impegnativo. Tcpdump è vostro amico.

Per ottenere il risultato voluto occorre:
 * Gestire gli interni in Asterisk nel file users.conf, unico posto dove è possibile inserire dati per il provisioning, oltre che per la gestione delle impostazioni sip, iax (volendo) e della segreteria.
 * Costruire un template di provisioning per i telefoni Grandstream, basandosi sulle informazioni reperibili sul loro sito (un esempio lo metto anche qui)
 * Opzionalmente, poter inserire valori personalizzati nel server DHCP per permettere il provisioning direttamente, senza dover toccare nulla della config di un telefono nuovo. Non potendo, occorrerà indicare ai nuovi telefoni l' URL per il provisioning a mano, e poi faranno tutto da soli.

Nota: in Asterisk deve essere caricato il modulo res_phoneprov, che in Debian / Devuan c'è di default, quindi non occorre fare nulla.

Altra nota: '''io uso questa roba in rete locale. Su internet occorre pensare bene ai rischi di sicurezza'''. Uno che riesca a scaricare una config di un telefono tramite gli URL di provisioning ha accesso alle password...



== Configurazione di Asterisk ==

In Asterisk occorre modificare divesi files:

 * '''/etc/asterisk/http.conf'''
 {{{
;
; Asterisk Builtin mini-HTTP server
;
; Questa configurazione è monca, ci sono un sacco di funzioni
; non usate. Vedi la versione originale del file per capirle.
;
[general]
; servername=Asterisk
;
enabled=yes
bindaddr=0.0.0.0
bindport=8080


; se setto a "yes", asterirsk serve i filea dentro a /usr/share/asterisk/static-http/
; con un url del tipo http://asterisk:8080/static/<nomefile>
; per esempio puo` servire per i firwmare.
; Siccome pare che ogni tanto il web server non parta se lo tengo a yes, lo metto a no...
enablestatic=no
}}}


 * '''/etc/asterisk/phoneprov.conf'''
 {{{
[general]
; il profilo di default se non e` specificato diversamente in users.conf
default_profile=gxp2130


; profilo per telefono GXP2130
; probabilmente funziona con molti altri telefoni, ma puo` avere senso farne diverse
; se si hanno telefoni molto diversi fra loro.
; il file "gxp2130.xml" e` il file di partenza che viene interpretato per sostituire le variabili.
; per fare funzionare tutto, va messo dentro a /usr/share/asterisk/phoneprov/
; La directory va creata, se manca. il path e` quello di "Data Directory" che si puo` verificare
; con il comando "core show settings"
; a questo punto, andando all' URL http://asterisk:8080/phoneprov/cfg112233445566.xml
; si potra` vedere il file compilato con la sostituzione delle variabili.
; (ovviamente se e` configurato in users.conf)

; qui sarebbe bello usare la funzione "TOLOWER" ma se lo faccio devo fare il preload 
; del modulo func_strings.so in modules.conf. Se mi ricordo di mettere i mac address in minuscolo
; allora TOLOWER non serve.

[gxp2130]
mime_type => text/xml
; cfg${TOLOWER(${MAC})}.xml => gxp2130.xml
cfg${MAC}.xml => gxp2130.xml


; firmware gxp2130
; lo devo dichiarare come file statico altrimenti non lo vede
; lo devo mettere dentro a /usr/share/asterisk/phoneprov/
mime_type => application/octet-stream
static_file => gxp2130fw.bin
}}}


 * '''/etc/asterisk/sip_notify.conf'''
 {{{
; Grandstream reboot e provision
; permette di forzare il reboot e il provision dei telefoni grandstream
; con il comando "sip notify grandstream-reboot <interno>"
; oppure il comando "sip notify grandstream-provision <interno>"
; con il firmware 1.0.11.6 del gxp2130 funzionano i comandi per lo snom
; (snom-check-cfg e snom-reboot)
[grandstream-reboot]
Event=>check-sync
[grandstream-provision]
Event=>resync
}}}


 * '''/etc/asterisk/users.conf'''
 {{{
[general]

; qui stanno i default validi per tutti
; se voglio un override lo posso fare nel singolo interno. qui oppure
; nel file conf specifico (sip.conf per esempio)

fullname = New User
userbase = 100 ; da dove iniziamo ad allocare gli interni
hasvoicemail = no ; non ha la segreteria di default (se metto yes qui, poi ce l'hanno tutti)
vmsecret = abbacabba ; password della segreteria impossibile da digitare, cosi` il default e` "inaccessibile"
hassip = yes
hasiax = no
hash323 = no
hasmanager = no ; dare accesso a AMI o no?
;managerread = system,call,log,verbose,command,agent,user,config
;managerwrite = system,call,log,verbose,command,agent,user,config


; sistema di provisioning dei telefoni: per funzionare richiede 
; necessariamente questi parametri:
; username = <numero interno>
; macaddress = 112233445566
; autoprov = yes
; profile = gxp2130
; vmexten = numero da chiamare per ascoltare la segreteria


;##################################
; Interni SIP
;##################################

; ATTENZIONE: in sip.conf "username" è deprecato e si usa "defaultuser"
; qui invece NO. Si deve usare username.


; interno senza mailbox personale
; su un telefono dietro un nat
[101]
hassip=yes
fullname=Cellulare
hasvoicemail=no ; non fornisco una casella per questo interno
username=101
secret=PASSWORD
host=dynamic
context=interni_uscenti
subscribecontext=interni
dtmfmode=rfc2833
pickupgroup=1
callgroup=1
mailbox=1 ; usa la mailbox 1 non avendone una sua
call-limit=4
qualify=4000
directmedia=no
nat=yes ; Il telefono e` dietro a un router che fa nat
;deny=0.0.0.0/0.0.0.0
;permit=192.168.0.0/255.255.0.0



; un interno di prova con la mailbox personale
; su un telefono GXP2130 con provisioning
; dietro a un nat
[104]
hassip=yes
fullname=prova gxp2130
hasvoicemail=yes ; creo una mailbox per lui
vmsecret=1234 ; password della sua mailbox
email=USER@DOMAIN.TLD ; email della sua mailbox
vmexten=*8010 ; necessario per il provisioning (tasto busta)
username=104
secret=PASSWORD
host=dynamic ; necessario per consentire la registrazione da ip non fisso
context=interni_uscenti
subscribecontext=interni
dtmfmode=rfc2833
pickupgroup=1
callgroup=1
mailbox=1 ; aggiunge la mailbox 1 alla sua personale (104) in modo che il LED lampeggi per tutte e due.
call-limit=3
qualify = yes
directmedia=no
nat=yes
macaddress=112233445566 ; mac address per il provisioning
autoprov=yes ; crea la configurazione per il provisioning
profile=gxp2130 ; modello di telefono per il provisioning
vmexten=*8011 ; numero da chiamare che viene associato al tasto "busta" per il provisioning
}}}


== Configurazione di un template per il telefono ==

Occorre ora creare una directory "phoneprov" dentro a /usr/share/asterisk (ovviamente Asterisk deve poter leggerne il contenuto) e poi ci metteremo dentro i files di template. Nel nostro esempio, il template è uno solo, e si chiama "gxp2130.xml".

Questo è un esempio di template nel file '''/usr/share/asterisk/phoneprov/gxp2130.xml'''
 {{{

<?xml version="1.0" encoding="UTF-8" ?>

	<!--####################-->
	<!-- config per gxp2130 -->
	<!--####################-->

<gs_provision version="1">
<config version="1">

	<!--Config account e user (account 1)-->
	
	<!--# Account Active. 0 - No, 1 - Yes. Default is 1-->
	<P271>1</P271>
	<!--# Account Name-->
	<P270>${USERNAME}</P270>
	<!--# SIP Server-->
	<P47>${SERVER}:${SERVER_PORT}</P47>
	<!--# SIP outbound proxy-->
	<P48>${SERVER}:${SERVER_PORT}</P48>
	<!--# SIP User ID-->
	<P35>${USERNAME}</P35>
	<!--# SIP Authenticate ID-->
	<P36>${USERNAME}</P36>
	<!--# SIP Authenticate Password-->
	<P34>${SECRET}</P34>
	<!--# Name (Display Name, e.g., John Doe)-->
	<P3>${DISPLAY_NAME}</P3>
	<!--# voicemail extension (per il tasto "busta")-->
	<P33>${VOICEMAIL_EXTEN}</P33>


	<!--Firmware server-->
	<P192>${SERVER}:8080/phoneprov</P192>
	<P6767>1</P6767>

	<!--config server-->
	<P237>${SERVER}:8080/phoneprov</P237>
	

	<!-- Features varie -->
	<!-- Dial plan con aggiunta di **x+ -->
	<P290>{x+|*x+|*xx*x+|**x+}</P290>
	<!--Unregister On Reboot. 0 - No, 1 - Yes. Default is 0-->
	<P81>1</P81>
	<!--Enable Call Features.  0 - No, 1 - Yes. Default is 1-->
	<P191>1</P191>
	<!--Call Log. 0 - Log All, 1 - Log Incoming/Outgoing only, 2 - Disable Call Log.-->
	<P182>1</P182>
	<!--Allow Auto Answer by Call-Info. 0 - No, 1 - Yes. Default is 0-->
	<P298>1</P298>
	<!--Play warning tone for Auto Answer Intercom. 0 - No, 1 - Yes. Default is 0 -->
	<P26072>1</P26072>
	<!--# Custom Call-Info for Auto Answer. -->
	<!-- <P2356></P2356> -->
	<!--# Key as Send. 0 - Disabled, 1 - Pound (#), 2 - Star (*). Default is 1-->
    	<P72>0</P72>
	<!--Preferred vocoder (in ordine dal primo in avanti)-->
	<!--metto PCMA prima e PCMU dopo, il default e` il contrario-->
	<P57>8</P57>
	<P58>0</P58>
	<!--Auto-Attended Transfer. 0 - No, 1 -Yes. Default is 0-->
	<P1376>0</P1376>
	

	<!-- Display, lingua, data/ora -->

	<!--# Enable weather update. 0 - No, 1 - Yes. Default is 1-->
	<P1402>0</P1402>
	<!--# Display Language. Default is auto-->
	<P1362>it</P1362>
	<!--# Screensaver. 0 - No, 1 - Yes. Default is 1-->
	<P2918>0</P2918>
	<!--# Backlight Brightness.-->
	<!--# Active. Default is 100.-->
	<P334>100</P334>
	<!--# Idle. Default is 60.-->
    	<P335>10</P335>
	<!--Disable Missed Call Backlight. 0 - No, 1 - Yes, 2 - Yes, but flash MWI LED. Default is 0-->
	<P351>1</P351>
	<!--# NTP Server-->
    	<P30>${SERVER}</P30>
	<!--# Time zone-->
	<!--# P64 = CET-1CEST-2,M3.5.0/02:00:00,M10.5.0/03:00:00 - GMT+01:00 (Paris, Vienna, Warsaw, Roma, Madrid, Prague, Berlin, Budapest, Amsterdam, Belgium)-->
	<P64>CET-1CEST-2,M3.5.0/02:00:00,M10.5.0/03:00:00</P64>
	<!--# Time Display Format. 0 - 12 Hour, 1 - 24 Hour-->
	<P122>1</P122>


	<!-- Associazione suonerie per interni e esterni -->

	<!--# Matching Incoming Caller ID. Matching Rule 1-->
    	<P1488>uno</P1488>
	<!--# Matching Rule 1 Distinctive Ringtone-->
	<!--# 0 - system ring tone, 1 - custom ring tone 1, 2 - custom ring tone 2, 3 - custom ring tone 3. Default is 0.-->
	<P1489>1</P1489>
	<!--# Matching Incoming Caller ID. Matching Rule 2-->
    	<P1490>due</P1490>
	<!--# Matching Rule 2 Distinctive Ringtone-->
	<!--# 0 - system ring tone, 1 - custom ring tone 1, 2 - custom ring tone 2, 3 - custom ring tone 3. Default is 0.-->
    	<P1491>2</P1491>
	<!--# Matching Incoming Caller ID. Matching Rule 3-->
	<P1492>tre</P1492>
	<!--# Matching Rule 3 Distinctive Ringtone-->
	<!--# 0 - system ring tone, 1 - custom ring tone 1, 2 - custom ring tone 2, 3 - custom ring tone 3. Default is 0.-->
    	<P1493>3</P1493>


	<!-- Configurazione multicast paging -->
		
	<!--# Priority 10-->
	<!--# Listening Address-->
	<P1587>224.1.1.1:6767</P1587>
	<!--# Label-->
	<P1588>Annuncio_generale</P1588>




	<!-- Rubrica in XML generata su Asterisk -->
        <!-- # Enable Phonebook XML Download. # 0 - Disabled, 1 - Enabled, use HTTP, 2 - Enabled, use TFTP, 3 - Enabled, use HTTPS -->
        <P330>1</P330>
	<!-- Phonebook XML Server Path -->
	<P331>${SERVER}/phonebook.php</P331>
	<!-- Phonebook Download Interval (in minutes) (5-720) -->
	<P332>5</P332>
	<!-- Phonebook Key Function. 0 - Default, 1 - LDAP Search, 2 - Local Phonebook, 3 - Local Group, 4 - Broadsoft Phonebook -->
	<P1526>2</P1526>
        <!-- Remove Manually-edited entries on Download. 0 - No, 1 - Yes. Default is 1 -->
        <P333>0</P333>


	<!--## Programmable Keys/Physical Multi-Purpose Keys - GXP2130 only-->
		
	<!--tasto 1 (tipo tasto - account - nome - numero) -->
	    <P323>1</P323>
	    <P301>0</P301>
	    <P302>Cellulare</P302>
	    <P303>101</P303>
	<!--tasto 2-->
	    <P324>1</P324>
	    <P304>0</P304>
	    <P305>Cordless</P305>
	    <P306>102</P306>
	<!--# 3-->
	    <P325>1</P325>
	    <P307>0</P307>
	    <P308>Pc</P308>
	    <P309>103</P309>
	<!--# 4-->
	    <P326>1</P326>
	    <P310>0</P310>
	    <P311>Pippo</P311>
	    <P312>103</P312>
	<!--# 5-->
	    <P327>1</P327>
	    <P313>0</P313>
	    <P314>Topolino</P314>
	    <P315>104</P315>
	<!--# 6-->
	    <P328>1</P328>
	    <P316>0</P316>
	    <P317>Papaerino</P317>
	    <P318>105</P318>
	<!--#7-->
	    <P329>1</P329>
	    <P319>0</P319>
	    <P320>park1</P320>
	    <P321>701</P321>
	<!--#8 -->
	    <P353>1</P353>
            <P354>0</P354>
            <P355>park2</P355>
            <P356>702</P356>

</config>
</gs_provision>
}}}

== Collaudo ==

Ora, se dopo aver dato l'ennesimo reload ad asterisk, andiamo con un browser a {{{http://<nome o ip del server>:8080/phoneprov/cfg112233445566.xml}}} dovremmo vedere il template XML di qui sopra, con dentro però tutti i valori sostituiti nel template, in modo da essere personalizzato per il nostro interno di prova che ha questo mac address.

Una cosa PESSIMA di questo sistema è che non esiste alcun log del server http contenuto in Asterisk (se c'è, io non l'ho trovato) per cui se qualcosa non va, auguri a capire perché.


== Configurazione dei telefoni ==

''' Nota: questa operazione non è necessaria se usiamo il DHCP come indicato sotto, oppure se usiamo Apache e il DNS come indicato sotto'''

Ora dovremo solo dire ai telefoni dove si trova il server del provisioning. Per farlo, possiamo andare nella loro interfaccia web e indicare l' URL del "config server" come {{{http://<nome o ip del server>:8080/phoneprov/}}} oppure possiamo andare sul server DHCP della LAN (quello da cui i telefoni prendono l' indirizzo ip) e definire una opzione speciale, che viene usata solo dai telefoni Grandstream, ove indicargli da dove fare il provisioning. 


== Configurazione del DHCP ==

''' Nota: questa operazione non è necessaria se usiamo Apache e il DNS come indicato sotto, oppure se configuriamo i telefoni come indicato sopra'''

Se non vogliamo configurare tutti i telefoni uno per uno come indicato sopra, dovremo aggiungere al nostro server DHCP l'opzione numero 66, ovvero "tftp-server-name" (anche se usiamo http), oppure in alternativa la 43, che pero` richiede un encoding più complesso.

Come farlo, dipende dal server DHCP che usate. Cosa metterci dentro, invece, è la stringa {{{http://<nome o ip del server>:8080/phoneprov}}}. 


== Configurazione di Apache come proxy ==

''' Nota: questa operazione non è necessaria se usiamo il DHCP come indicato sopra, oppure se configuriamo i telefoni come indicato sopra'''

'''ATTENZIONE, IMPORTANTE: Se usate apache come proxy, le richieste di provisioning arriveranno ad Asterisk da 127.0.0.1, ed esso valorizzerà la variabile SERVER con 127.0.0.1. Questo romperà completamente la vostra configurazione se usate "SERVER" dentro ai files di template. Suggerisco quindi di usare valori hardcoded nel file di template al posto della variabile SERVER se volete usara Apache come proxy'''

Se per qualche motivo non volete o non potete pastrocchiare con il DHCP, potete fare un altro accrocchio con Apache come proxy. Tuttavia vi serve per forza avere l'accesso al DNS della LAN. I telefoni per default fanno il provisioning dall' url "http://fm.grandstream.com/gs". Se riusciamo a fare in modo che sia il nostro server Asterisk a rispondere a quell'URL, possiamo fare il provisioning senza dover inserire opzioni nel DHCP (e senza modificare a mano ogni telefono). Tuttavia dobbiamo comunque mettere mano al DNS locale.

 * Modificare il server DNS della lan in modo che risolva l'host "fm.grandstream.com" con l' ip del nostro server Asterisk
 * Installare Apache2 sul server Asterisk
 * Abilitare i moduli proxy necessari: {{{a2enmod proxy http_proxy}}}
 * Creare la configurazione necessaria dentro a {{{/etc/apache2/sites.available/fm.grandstream.com.conf}}}, fatta così:
 {{{
<VirtualHost *:80>
        ServerName fm.grandstream.com
        ProxyPreserveHost On
        ProxyPass "/gs/" "http://localhost:8080/phoneprov/"
</VirtualHost>
}}}
 * Abilitare la configurazione appena fatta: {{{a2ensite fm.grandstream.com.conf}}}
 * Riavviare Apache