Manpages

NOME

sitecopy − gestisce le copie remote di siti web

SINTASSI

sitecopy [opzioni] [modalità operativa] nomesito ...

DESCRIZIONE

sitecopy serve a copiare su server remoti i siti web di cui si ha una copia locale. Basta un solo comando per caricare sul server i file che sono stati modificati localmente e cancellarvi quelli cancellati localmente, in modo da tenere il sito remoto sincronizzato con quello locale. L’idea è quella di evitare di dover caricare e cancellare i file uno per uno usando un client FTP. sitecopy è anche in grado di accorgersi se un file è stato spostato localmente, in modo da spostarlo anche nella copia remota.

Sono supportati FTP, WebDAV e altri tipi di server basati su HTTP (ad esempio AOLserver e Netscape Enterprise).

INTRODUZIONE

Questo capitolo spiega come iniziare a gestire un sito web usando sitecopy. Dopo aver introdotto i concetti di base, vengono descritte due situazioni: la prima, in cui il sito è già stato caricato sul server remoto; la seconda, in cui non lo si è ancora fatto. Infine vengono descritte le attività di gestione ordinaria.

Aspetti basilari
Se non è stato ancora fatto, occorre creare un file di configurazione, che conterrà le informazioni riguardanti i siti che si intende amministrare. Occorre anche creare una directory degli archivi, che sitecopy usa per tenere traccia dello stato dei file su ognuno dei siti remoti. Il file di configurazione e la directory degli archivi devono entrambi essere accessibili solo da un utente, altrimenti sitecopy non si avvierà. Per creare la directory degli archivi con i permessi corretti, si usi il comando

mkdir -m 700 .sitecopy

dalla propria home directory. Per creare il file di configurazione, si usino i comandi

touch .sitecopyrc

chmod 600 .sitecopyrc

dalla propria home directory. Fatto questo, occorre inserire nel file di configurazione le informazioni sui siti, così come mostrato nel capitolo CONFIGURAZIONE.

Sito remoto esistente
Se il sito è già stato caricato sul server remoto, ci si assicuri che i file locali siano sincronizzati con quelli remoti e si esegua

sitecopy --catchup nomesito

dove nomesito è il nome del sito specificato dopo la direttiva site nel file di configurazione.

Se non si ha una copia locale del sito, è possibile usare la modalità scaricamento (fetch) per scoprire cosa c’è sul sito remoto e il modalità sincronizzazione per scaricarlo. La modalità scaricamento (fetch) funziona bene con i server WEBDAV, mentre può non funzionare con tutti i server FTP. Si esegua

sitecopy --fetch nomesito

per scaricare la lista dei contenuti del sito; se l’operazione ha successo si esegua

sitecopy --synch nomesito

per scaricare una copia locale del sito. NON eseguire questa operazione se si ha già una copia locale del sito.

Sito remoto nuovo
Occorre assicurarsi che sia stata creata sul server la directory radice del sito ed eseguire:

sitecopy --init nomesito

dove nomesito è il nome del sito specificato dopo la direttiva site nel file di configurazione.

Gestione del sito
Dopo aver impostato il sito con uno dei modi illustrati nei paragrafi precedenti, è possibile cominciare a modificare i file locali. Quando si vuole aggiornare la copia remota del sito, occorre eseguire:

sitecopy --update nomesito

e tutti i file modificati verranno caricati sul server. I file cancellati localmente saranno cancellati anche sulla copia remota, a meno di aver specificato l’opzione nodelete nel file di configurazione. Se si spostano dei file da una directory all’altra, i file remoti verranno prima cancellati dal server e poi caricati di nuovo, a meno di non aver specificato l’opzione checkmoved nel file di configurazione.

In ogni momento è possibile vedere quali modifiche sono state fatte al sito locale rispetto all’ultimo aggiornamento, eseguendo

sitecopy nomesito

che mostrerà un’elenco delle differenze.

Problemi di sincronizzazione
In alcune circostanze, i file presenti sul sito remoto potrebbero essere diversi da quelli che sitecopy pensa siano sul sito remoto. Questo può succedere, per esempio, se la connessione al server viene interrotta durante un aggiornamento. Quando si presentano queste situazioni, occorre usare la modalità scaricamento (fetch) per scaricare dal server remoto la lista dei file che compongono il sito.

INVOCAZIONE

Per le operazioni normali occorre specificare una singola modalità operativa, seguita dalle opzioni desiderate e da uno o più nomi di siti. Ad esempio:

sitecopy --update --quiet primosito altrosito

aggiornerà silenziosamente i siti chiamati "primosito" e "altrosito".

MODALITÀ OPERATIVE

-l, --list

Modalità Lista − produce una lista di tutte le differenze tra i file locali e la copia remota per i siti specificati.

-ll, --flatlist

Modalità Lista Semplice − come la modalità lista, tranne che il risultato è in un formato adatto ad essere analizzato da un programma o script esterno. È disponibile uno script AWK changes.awk, che trasforma la lista semplice in una pagina HTML.

-u, --update

Modalità Aggiornamento − aggiorna la copia remota dei siti specificati.

-f, --fetch

Modalità Scaricamento − scarica l’elenco dei file presenti sul server remoto, aggiornando l’archivio di stato del sito. Si noti che questa modalità è supportata solo in misura limitata dai server FTP: il server deve accettare il comando MDTM e deve implementare LIST con un "ls" in stile Unix.

-s, --synchronize

Modalità Sincronizzazione − sincronizza la copia locale del sito usando la copia remota come riferimento. ATTENZIONE: Questa modalità sovrascrive i file locali. Da usare con cautela.

-i, --initialize

Modalità Inizializzazione − inizializza i siti specificati, indicando a sitecopy che NON ci sono file sul server remoto.

−c, −−catchup

Modalità Riallineamento − indica a sitecopy che il sito remoto è esattamente come il sito locale (riallinea l’archivio di stato del sito con la copia locale).

-v, --view

Modalità Visualizzazione − mostra tutte le definizioni dei siti contenute nel file di configurazione.

-h, --help

Mostra informazioni di aiuto.

-V, --version

Mostra informazioni sulla versione.

OPZIONI

-y, --prompting

Applicabile solo in Modalità Aggiornamento , chiederà conferma all’utente per ogni operazione di aggiornamento (ad es. creazione di una directory, caricamento di un file ecc.)

-r RCFILE, --rcfile=RCFILE

Specifica una posizione alternativa per il file di configurazione.

-p PATH, --storepath=PATH

Specifica una posizione alternativa per la directory degli archivi.

-q, --quiet

Visualizzazione silenziosa: mostra solo il nome del file per ogni aggiornamento compiuto.

-qq, --silent

Visualizzazione molto silenziosa: non mostra nulla.

-o, --show-progress

Applicabile solo in Modalità Aggiornamento, mostra la percentuale di completamento dei trasferimenti di dati.

-k, --keep-going

Prosegue anche in caso di errori in Modalità Aggiornamento o Modalità Sincronizzazione

-a, --allsites

Esegue l’operazione specificata su tutti i siti; applicabile in tutte le modalità eccetto che in Modalità Visualizzazione, per cui non ha alcun effetto.

-d MASCHERA, --debug=CODICE[,CODICE...]

Abilita il debugging. Occorre specificare una lista di codici separati da virgole. I codici disponibili sono:
socket Gestione del socket
files Gestione dei file
rcfile Analizzatore del file di configurazione
http Driver HTTP
httpbody Mostra i corpi delle risposte HTTP
ftp Driver FTP
xml Informazioni sul parsing XML
xmlparse Informazioni di basso livello sul parsing XML
httpauth Informazioni di autenticazione HTTP
cleartext Mostra le password in chiaro

Le password sono oscurate nell’output del debugging, a meno che non venga usato il codice cleartext. Un esempio di uso del debugging è per controllare il funzionamento della modalità scaricamento (fetch) con un server FTP:

sitecopy --debug=ftp,socket --fetch nomesito

CONCETTI

Lo stato di un sito è la fotografia del sito, salvata nella directory degli archivi (~/.sitecopy/). Il file di archivio è usato per conservare questo stato tra un aggiornamento e l’altro. In modalità aggiornamento, sitecopy costruisce una lista di file per ogni sito analizzando la copia locale, legge lo stato del sito dall’archivio e confronta i due, determinando i file modificati, quelli spostati e così via.

CONFIGURAZIONE

La configurazione è eseguita attraverso il file di configurazione (rcfile). Questo file contiene una serie di definizioni di siti. Ad ogni definizione di sito è associato un nome univoco, che è usato per indicare il sito quando si esegue sitecopy.

Ogni definizione di sito contiene i dettagli del server che ospita il sito, la modalità di accesso al server, la posizione della copia locale del sito e altre opzioni per il sito.

Definizione di sito
Una definizione di sito è composta da una serie di righe:

site nomesito
server
nome-server
remote
directory-radice-remota
local
directory-radice-locale
[ port numero-porta ]
[ username nomeutente ]
[ password password ]
[ proxy-server nome-proxy
proxy-port
numero-porta ]
[ url URL-del-sito ]
[ protocol { ftp | webdav } ]
[ ftp nopasv ]
[ ftp showquit ]
[ ftp { usecwd | nousecwd } ]
[ http expect ]
[ http secure ]
[ safe ]
[ state { checksum | timesize } ]
[ permissions { ignore | exec | all } ]
[ symlinks { ignore | follow | maintain } ]
[ nodelete ]
[ nooverwrite ]
[ checkmoved [renames] ]
[ tempupload ]
[ exclude modello ]...
[ ignore modello ]...
[ ascii modello ]...

Qualsiasi cosa segua un "#" in una riga è considerato un commento. È possibile racchiudere i valori tra virgolette e prefissare i caratteri con una barra obliqua inversa. Ad esempio, per specificare il modello di exclude *#, si scriva:

exclude "*#"

Opzioni per il server remoto
La direttiva server è usata per specificare il server remoto su cui risiede il sito. Può trattarsi di un nome DNS o di un indirizzo IP. La connessione viene tentata sulla porta predefinita per il protocollo usato, ma è anche possibile indicare una porta diversa con la direttiva port. sitecopy supporta i protocolli WebDAV o FTP: la direttiva protocol, che può assumere i valori webdav o ftp specifica quale usare. Il protocollo predefinito è FTP.

Le direttive proxy-server e proxy-port possono essere usate per specificare un server proxy. I server proxy al momento sono supportati solo con WebDAV.

Se il server FTP non supporta la modalità passiva (PASV), occorre usare la direttiva ftp nopasv. Per mostrare i messaggi ricevuti dai server alla chiusura della connessione, si usi la direttiva ftp showquit. Se il server permette di caricare file solo nella directory corrente, si usi la direttiva ftp usecwd (un possibile sintomo: "overwrite permission denied"). Si noti che la directory remota (direttiva remote) dev’essere un percorso assoluto (iniziante per "/"), altrimenti usecwd sarebbe ignorato.

Se il server WebDAV supporta la risposta 100-continue, ad es. Apache 1.3.9 e successivi, si consiglia di usare la direttiva http expect. In questo modo si risparmieranno banda e tempo durante gli aggiornamenti.

Per autenticare l’utente sul server, vengono usate le direttive username e password. Se non viene specificata la password, verrà cercata nel file ~/.netrc, se esiste. Si veda ftp(1) per la sintassi di questo file.

Con WebDAV vengono supportate l’autenticazione base e quella digest. Si noti che l’autenticazione base non dev’essere usata, a meno che la connessione non sia di tipo sicuro.

L’URL completo usato per accedere al sito può essere specificato in modo opzionale con la direttiva url. Questa è usata solo per includere l’URL del sito nelle pagine "Cambiamenti recenti" che possono essere generate in modalità lista semplice. L’URL NON deve avere una barra obliqua alla fine; un esempio valido è

url http://www.site.com/mysite

Se viene usata la direttiva tempupload, i file modificati vengono caricati con un prefisso «.in.», quindi rinominati con il corretto nome quando il caricamento è completato.

Stato dei file
Lo stato dei file è registrato nei file di archivio (~/.sitecopy/*) ed è usato per scoprire quando un file è stato modificato. Sono supportati due metodi, selezionabili con la direttiva state che può avere argomenti: timesize (quello predefinito) e checksum.

timesize usa la data di ultima modifica e la dimensione del file per capire quando il file è stato modificato. checksum usa un checksum MD5 per controllare le modifiche ai contenuti dei file.

Si noti che usare il checksum MD5 implica la lettura dell’intero file e quindi è più lento che usare semplicemente la data di ultima modifica e la dimensione. Può essere utile per esempio se si sta usando un sistema di controllo delle versioni che aggiorna la data dei file anche quando i contenuti del file non vengono modificati (ad esempio durante le operazioni di «checkout»).

Modalità sicura
La modalità sicura è abilitata usando la direttiva safe. Quando è in uso, ogni volta che un file viene caricato sul server viene registrata la data di modifica del file sul server. In seguito, quando il file modificato localmente viene caricato sul server, viene letta la data di modifica del file sul server e confrontata con quella registrata l’ultima volta. Se queste differiscono, significa che la copia remota del file è stata alterata da terzi: viene mostrato un messaggio di avvertimento e la copia locale del file non sovrascriverà la copia remota, per evitare di perdere eventuali modifiche fatte.

La modalità sicura può essere usata con server FTP o WebDAV; se si usa Apache/mod_dav, è richiesto mod_dav 0.9.11 o successivo.

Nota La modalità sicura non può essere usata insieme all’opzione nooverwrite (si veda oltre).

Posizioni dei file
La direttiva remote specifica la directory radice della copia remota del sito. Può avere la forma di un percorso assoluto, ad es.

remote /www/mysite/

Per FTP, la directory può essere specificata anche relativamente alla directory di login, nel qual caso va prefissata con "~/", ad esempio:

remote ~/public_html/

La direttiva local specifica la directory che ospita la copia locale del sito. Questa può essere specificata relativamente alla propria home directory (contenuta nella variabile di ambiente $HOME), sempre usando il prefisso "~/".

local ~/html/foosite/

local /home/fred/html/foosite/

sono equivalenti, se $HOME ha valore "/home/fred".

Gli argomenti di entrambe le direttive remote e local possono terminare con una barra obliqua inversa, ma non è richiesto.

Gestione dei permessi sui file
La gestione dei permessi sui file è regolata dalla direttiva permissions, che può assumere uno dei seguenti tre valori:

ignore

per ignorare completamente i permessi,

exec

per copiare i permessi dei soli file eseguibili,

all

per copiare i permessi di tutti i file.

Questo può essere utile, ad esempio, per assicurarsi che i permessi dei file CGI siano corretti. L’opzione, al momento, è ignorata dai server WebDAV; per i server FTP, i permessi vengono modificati attraverso un comando chmod remoto.

Gestione dei link simbolici
I link simbolici che si trovano nella copia locale possono essere ignorati, seguiti o mantenuti. In modalità «follow», al posto dei link simbolici verranno caricati i file ad essi collegati. In modalità «maintain» i link verranno creati anche sul server remoto; si veda oltre, per maggiori informazioni. La modalità usata per ogni sito è specificata con la direttiva symlinks, che può assumere i valori ignore, follow o maintain per selezionare la modalità corrispondente.

La modalità predefinita è ignore, ossia i link simbolici che si trovano nel sito locale vengono ignorati.

Modalità «maintain» dei link simbolici
Questa modalità al momento è supportata solo dal driver WebDAV e funziona solo con i server che implementano le "collezioni avanzate" WebDAV, cosa che non è ancora molto comune. L’obiettivo del link sul server è letteralmente copiato usando l’obiettivo del link sulla copia locale. Suggerimento: è possibile usare gli URL:
ln -s "http://www.qualcosa.org/"; qualcosa_su_home

In questo modo il client può impostare un "302 Redirect", senza che ci sia bisogno di modificare la configurazione del server.

Cancellare e spostare i file remoti
La direttiva nodelete può essere usata per impedire che i file remoti vengano cancellati. Questo può essere utile se sul server remoto si tiene una grande quantità di dati che non si vuole conservare anche localmente.

Se il server non permette di caricare i file modificati sovrascrivendo i file esistenti, è possibile usare la direttiva nooverwrite. Quando viene usata, il file remoto viene cancellato prima che sia caricata la versione modificata.

Se viene usata la direttiva checkmoved, sitecopy controllerà i file che sono stati spostati localmente e li sposterà anche sulla copia remota al momento dell’aggiornamento.

Se viene usata la direttiva checkmoved renames, sitecopy controllerà i file che sono stati spostati o rinominati localmente. Quest’opzione può essere usata solo insieme all’opzione state checksum.

ATTENZIONE

Se non si usano i checksum MD5 (ossia la direttiva state checksum) per determinare lo stato dei file, NON usare la direttiva checkmoved se vengono spostati file che si trovano in diverse directory, ma che hanno dimensione, data di modifica e nome identici. È una situazione molto improbabile, ma da tenere in considerazione.

Escludere i file
I file possono essere esclusi dalla lista dei file usando la direttiva exclude, che accetta i modelli di globbing della shell. Ad esempio, si usi
exclude
*.bak
exclude
*~
exclude
"#*#"
per escludere tutti i file che hanno un’estensione .bak, che finiscono con una tilde (~) o che iniziano e finiscono con un «#». Non si dimentichi di proteggere o racchiudere tra virgolette eventuali caratteri "#", affinché non vengano interpretati come inizio di un commento!

Per escludere alcuni file in una particolare directory, basta semplicemente prefissare il modello con il nome della directory, includendo una barra obliqua iniziale. Ad esempio:

exclude /docs/*.m4
exclude
/files/*.gz
escluderà tutti i file con estensione .m4 nella directory "docs" del sito e tutti i file con estensione .gz nella directory "files".

Si può anche escludere un’intera directory, semplicemente specificando il nome della directory senza barra obliqua finale. Ad esempio:
exclude
/foo/bar
exclude
/where/else
escluderà le directory "foo/bar" e "where/else" del sito.

I modelli di esclusione vengono consultati mentre si analizza la copia locale e i file che corrispondono al modello non vengono aggiunti alla lista dei file. Questo significa che un file locale che è già stato caricato sul server e in seguito corrisponde a un modello di esclusione, verrà cancellato dal server.

Ignorare le modifiche locali ai file
La direttiva ignore è usata per istruire sitecopy a ignorare le modifiche locali fatte a un file. Se viene modificato un file che viene ignorato, il file non sarà caricato in modalità aggiornamento. I file ignorati verranno creati, spostati e cancellati come al solito.

La direttiva ignore viene usata allo stesso modo della direttiva exclude.

Si noti che la modalità di sincronizzazione sovrascriverà le modifiche fatte ai file ignorati.

Modalità di trasferimento FTP
Per specificare la modalità di trasferimento FTP per i file, si usi la direttiva ascii. Sui file trasferiti usando la modalità ASCII viene eseguita automaticamente la trasformazione dei terminatori di linea CRLF/LF. Ad esempio, si usi
ascii
*.pl
per caricare tutti i file con l’estensione .pl come testo ASCII. Questa direttiva non ha effetto con i server WebDAV (al momento).

VALORI DI RITORNO

Esistono valori di ritorno specifici per ogni modalità operativa. Se vengono specificati più siti sulla linea di comando, il valore di ritorno si riferisce all’ultimo sito specificato.

Modalità aggiornamento
-1 ... l’aggiornamento non è neanche iniziato - problema di configurazione
0 ... l’aggiornamento è stato eseguito con successo
1 ... si è verificato un errore da qualche parte
2 ... non è stato possibile connettersi o fare login sul server

Modalità lista (modalità predefinita)
-1 ... non è stato possibile formare la lista - problema di configurazione
0 ... il sito remoto non deve essere aggiornato
1 ... il sito remoto deve essere aggiornato

ESEMPI DI FILE DI CONFIGURAZIONE

Server FTP, utilizzo basilare
Il sito di Fred è ospitato sul server FTP "my.server.com" nella directory "public_html", che è la directory di login. La copia locale del sito è nella directory "/home/fred/html".

site mysite
server my.server.com
url http://www.server.com/fred
username fred
password juniper
local /home/fred/html/
remote ~/public_html/

Server FTP, utilizzo avanzato
Il sito di Frida è ospitato sul server FTP "ftp.elsewhere.com", nella directory "/www/frida/". La copia locale del sito è nella directory "/home/frida/sites/elsewhere/"

site anothersite
server ftp.elsewhere.com
username frida
password blahblahblah
local /home/frida/sites/elsewhere/
remote /www/frida/
# Frida vuole che siano ignorati i file con
# l’estensione .bak o che terminano per ~
exclude *.bak
exclude *~

Server WebDAV, utilizzo semplice
Questo esempio mostra l’uso di un server WebDAV.

site supersite
server dav.wow.com
protocol webdav
username pow
password zap
local /home/joe/www/super/
remote /

FILE

~/.sitecopyrc File di configurazione predefinito.
~/.sitecopy/
Directory che contiene gli archivi con lo stato dei siti remoti.
~/.netrc
File con le informazioni di autenticazione sui server remoti.

BUG

Problemi noti: le modalità scaricamento (fetch) e sincronizzazione NON sono affidabili sui server FTP. Se si ha bisogno di usare queste modalità in modo affidabile, invece di sitecopy si provi rsync.

Si prega di inviare le notifiche di errore e le richieste di miglioramenti a <sitecopy [AT] lyra.org> piuttosto che all’autore, visto che la mailing list è archiviata e può rappresentare una risorsa utile per tutti.

VEDERE ANCHE

rsync(1), ftp(1), mirror(1)

STANDARD

[Elencati solo come riferimento, non vi è alcuna dichiarazione di compatibilità con gli standard citati.]

RFC 959 - File Transfer Protocol (FTP)
RFC 1521
- Multipurpose Internet Mail Extensions Part One
RFC 1945
- Hypertext Transfer Protocol -- HTTP/1.0
RFC 2396
- Uniform Resource Identifiers: Generic Syntax
RFC 2518
- HTTP Extensions for Distributed Authoring -- WEBDAV
RFC 2616
- Hypertext Transfer Protocol -- HTTP/1.1
RFC 2617
- HTTP Authentication
REC-XML
- Extensible Markup Language (XML) 1.0
REC-XML-NAMES
- Namespaces in XML

DRAFT STANDARD

draft-ietf-ftpext-mlst-05.txt - Extensions to FTP
draft-ietf-webdav-collections-protocol-03.txt
- WebDAV Advanced Collections Protocol

AUTORE

Joe Orton e altri.
e-mail: sitecopy [AT] lyra.org
www: http://www.lyra.org/sitecopy/