BITS (Background Intelligent Transfer System) è un componente di Windows utilizzato dal sistema operativo per il download degli aggiornamenti. Tale componente è utilizzabile anche da programmatori e amministratori di sistema per il download/upload di file di grandi dimensioni su server web HTTP o REST e su file server SMB. BITS sfrutta la banda non utilizzata per trasferire dati preservando la reattività di altre applicazioni di rete inoltre, gestisce eventuali interruzioni di rete mettendo in pausa e riprendendo automaticamente i trasferimenti anche dopo un riavvio ed è in grado di operare anche quando la macchina non è loggata. BITS non funziona con tutti i download ma è necessario che anche il server supporti tale tecnologia.
Per sfruttare le potenzialità di BITS attraverso PowerShell, si utilizza il cmdlet Start-BitsTransfer.
Sintassi
Start-BitsTransfer
[-Asynchronous]
[-Dynamic]
[-CustomHeadersWriteOnly]
[-Authentication <String>]
[-Credential <PSCredential>]
[-Description <String>]
[-HttpMethod <String>]
[[-Destination] <String[]>]
[-DisplayName <String>]
[-Priority <String>]
[-TransferPolicy <CostStates>]
[-ACLFlags <ACLFlagValue>]
[-SecurityFlags <SecurityFlagValue>]
[-UseStoredCredential <AuthenticationTargetValue>]
[-ProxyAuthentication <String>]
[-ProxyBypass <String[]>]
[-ProxyCredential <PSCredential>]
[-ProxyList <Uri[]>]
[-ProxyUsage <String>]
[-RetryInterval <Int32>]
[-RetryTimeout <Int32>]
[-MaxDownloadTime <Int32>]
[-Source] <String[]>
[-Suspended]
[-TransferType <String>]
[-CustomHeaders <String[]>]
[-NotifyFlags <NotifyFlagValue>]
[-NotifyCmdLine <String[]>]
[-CertStoreLocation <CertStoreLocationValue>]
[-CertStoreName <String>]
[-CertHash <Byte[]>]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Descrizione
Il cmdlet Start-BitsTransfer crea un job Background Intelligent Transfer Service (BITS) per trasferire uno o più file tra un computer client e un server. Il parametro TransferType specifica la direzione del trasferimento. Per impostazione predefinita, dopo che il cmdlet inizia il trasferimento, il prompt dei comandi non è disponibile fino a quando il trasferimento non sarà completo o si verifica un errore. Se lo stato dell'oggetto BitsJob restituito è Error, il codice di errore e la descrizione sono contenuti nell'oggetto e possono essere utilizzati per l'analisi.
Parametri
-ACLFlags
Specifica il proprietario e le informazioni dell'elenco di controllo degli accessi (ACL) da mantenere per il job di trasferimento. É possibile specificare uno o più dei seguenti valori:
- o: Copia le informazioni sul proprietario con il file.
- g: Copia le informazioni sul gruppo con il file.
- d: Copia le informazioni sulla lista di controllo degli accessi discrezionali (DACL) con il file.
- s: Copia le informazioni dell'elenco di controllo dell'accesso al sistema (SACL) con il file.
-Asynchronous
Indica che il cmdlet crea ed elabora il job di trasferimento BITS in background. Il prompt dei comandi riappare immediatamente dopo la creazione del lavoro di trasferimento BITS. L'oggetto BitsJob restituito può essere utilizzato per monitorare lo stato e il progresso del trasferimento.
-Authentication
Specifica il meccanismo di autenticazione da utilizzare sul server. I valori accettati per questo parametro sono:
- Basic: è uno schema in cui il nome utente e la password sono inviati in chiaro al server o al proxy.
- Digest: è uno schema challenge-response che usa una stringa di dati specificata dal server per la challenge.
- Ntlm: NT LAN Manager (NTLM) è uno schema challenge-response che usa le credenziali dell'utente per l'autenticazione in un ambiente di rete basato su Windows.
- Negotiate (l'impostazione predefinita): è uno schema challenge-response che negozia con il server o il proxy per determinare quale schema usare per l'autenticazione. Per esempio, questo valore di parametro permette la negoziazione per determinare se viene usato il protocollo Kerberos o NTLM.
- Passport: Passport è un servizio di autenticazione centralizzato fornito da Microsoft che offre un unico accesso per i siti membri.
-CertHash
Specifica un hash SHA1 che identifica il certificato.
-CertStoreLocation
Specifica la location da usare per cercare il certificato. I valori validi sono:
- CURRENT_USER
- LOCAL_MACHINE
- CURRENT_SERVICE
- SERVICES
- USERS
- CURRENT_USER_GROUP_POLICY
- LOCAL_MACHINE_GROUP_POLICY
- LOCAL_MACHINE_ENTERPRISE
-CertStoreName
Specifica il nome dello store di certificati. I valori validi sono:
- CA: Certification Authority certificates
- MY: Personal certificates
- ROOT: Root certificates
- SPC: Software Publisher Certificate
-Confirm
Chiede conferma prima di eseguire il cmdlet.
-Credential
Specifica le credenziali da usare per autenticare l'utente al server indicato nel valore del parametro Source. L'impostazione predefinita è l'utente corrente.
-CustomHeaders
Specifica una o più intestazioni HTTP personalizzate da includere nella richiesta al server. Specifica un array di stringhe.
-CustomHeadersWriteOnly
Indica che le intestazioni personalizzate HTTP per questo job sono in sola scrittura.
Questo parametro viene utilizzato quando le intestazioni personalizzate includono informazioni di sicurezza. Altri programmi sullo stesso computer non possono leggere l'intestazione. Il processo BITS può leggere le intestazioni e inviarle attraverso la connessione HTTP.
Dopo aver impostato le intestazioni in solo scrittura per un job non sarà possibile modificarle.
-Description
Permette di specificare una descrizione del job di trasferimento BITS. La descrizione è limitata a 1.024 caratteri.
-Destination
Specifica un array che contiene la posizione di destinazione e i nomi dei file che si intende trasferire. I nomi di destinazione sono accoppiati con i corrispondenti nomi di file sorgente. Per esempio, il primo nome di file specificato nel parametro Source corrisponde al primo nome di file nel parametro Destination, e il secondo nome di file nel parametro Source corrisponde al secondo nome di file nel parametro Destination. I parametri Source e Destination devono avere lo stesso numero di elementi, altrimenti il comando produce un errore.
-DisplayName
Specifica un nome di visualizzazione per il job di trasferimento BITS. Il nome visualizzato fornisce un modo semplice per differenziare i trasferimenti BITS.
-Dynamic
Indica che il trasferimento utilizza l'impostazione dinamica.
-HttpMethod
Specifica un metodo per il trasferimento diverso dal metodo predefinito GET. Se si specifica GET, il parametro non ha effetto.
Se si specifica un metodo, il job prende la priorità in primo piano, che non può essere cambiata.
-MaxDownloadTime
Specifica il tempo massimo, in secondi, per il trasferimento dei file in un lavoro. Il valore predefinito è 7.776.000 secondi o 90 giorni.
-NotifyCmdLine
Specifica un programma da eseguire dopo che il job termina o fallisce con un errore. Il programma viene eseguito nel contesto dell'utente che esegue questa cmdlet.
Specifica il nome del programma ed eventuali parametri come un array di stringhe.
-NotifyFlags
Specifica il tipo di notifica dell'evento che vuoi ricevere, come gli eventi di trasferimento del lavoro. I valori validi sono:
1: Genera un evento quando tutti i file del job sono stati trasferiti.
2: Genera un evento quando si verifica un errore.
4: Disabilita le notifiche.
-Priority
Imposta la priorità del job di trasferimento BITS, che influenza l'uso della larghezza di banda. I valori accettati per questo parametro sono:
- Foreground (predefinito): Il trasferimento viene gestito in primo piano. I trasferimenti in primo piano competono per la larghezza di banda della rete con altre applicazioni, il che può ostacolare l'esperienza complessiva della rete dell'utente. Tuttavia, se il cmdlet Start-BitsTransfer viene utilizzato in modo interattivo, questa è probabilmente l'opzione migliore. Questo è il livello di priorità più alto.
- High: Il trasferimento avviene in background con un'alta priorità. I trasferimenti in background utilizzano la larghezza di banda di rete inattiva del computer client per trasferire i file.
- Normal: Il trasferimento avviene in background con una priorità normale. I trasferimenti in background utilizzano la larghezza di banda di rete inattiva del computer client per trasferire i file.
- Low: Il trasferimento avviene in background con una priorità bassa. I trasferimenti in background usano la larghezza di banda di rete inattiva del client per trasferire i file. Questo è il livello di priorità in background più basso.
-ProxyAuthentication
Specifica il meccanismo di autenticazione da usare al proxy web. I valori accettati per questo parametro sono:
- Basic: Basic è uno schema in cui il nome utente e la password sono inviati in chiaro al server o al proxy.
- Digest: Digest è uno schema challenge che usa una stringa di dati specificata dal server per la challenge.
- Ntlm: NTLM è uno schema challenge-response che usa le credenziali dell'utente per l'autenticazione in un ambiente di rete basato su Windows.
- Negotiate (l'impostazione predefinita): Negotiate è uno schema challenge-response che negozia con il server o il proxy per determinare quale schema usare per l'autenticazione. Per esempio, questo valore di parametro permette la negoziazione per determinare se viene usato il protocollo Kerberos o NTLM.
- Passport: Passport è un servizio di autenticazione centralizzato fornito da Microsoft che offre un unico accesso per i siti membri.
-ProxyBypass
Specifica una lista di nomi di host da usare per una connessione diretta. Gli host nell'elenco vengono provati in ordine fino a quando non si ottiene una connessione di successo. Se si specifica questo parametro il cmdlet bypassa il proxy. Se questo parametro viene utilizzato, il parametro ProxyUsage deve essere impostato su Override, altrimenti si verificherà un errore.
-ProxyCredential
Specifica le credenziali da utilizzare per autenticare l'utente al proxy. Con il cmdlet Get-Credential è possibile creare un valore per questo parametro.
-ProxyList
Specifica una lista di proxy da utilizzare. I proxy nell'elenco vengono provati in ordine fino a quando non si ottiene una connessione di successo. Se questo parametro è specificato e ProxyUsage è impostato su un valore diverso da Override, la cmdlet genera un errore.
-ProxyUsage
Specifica le impostazioni di utilizzo del proxy. I valori accettati per questo parametro sono:
- SystemDefault (il valore predefinito): Usa le impostazioni proxy predefinite del sistema.
- NoProxy: Non usare un proxy per trasferire i file. Utilizzare questa opzione quando si trasferiscono file all'interno di una rete locale (LAN).
- AutoDetect: Rileva automaticamente le impostazioni proxy. Il BITS rileva le impostazioni proxy per ogni file nel lavoro.
- Sovrascrivi: Specifica i proxy o i server da usare. Se viene specificato anche il parametro ProxyList, vengono utilizzati i proxy di quella lista. Se viene specificato anche il parametro ProxyBypass, vengono utilizzati i server di quella lista. In entrambi i casi, viene utilizzato il primo membro della lista. Se il primo membro non è raggiungibile, vengono provati i membri successivi fino a quando un membro viene contattato con successo.
-RetryInterval
Specifica la lunghezza minima di tempo, in secondi, che il BITS attende prima di un ulteriore tentativo di trasferimento dopo un errore. Il valore minimo consentito è 60 secondi. Se questo valore supera il valore RetryTimeout dell'oggetto BitsJob, il BITS non ritenta il trasferimento ma imposta lo stato Error.
Il valore predefinito è 600 secondi (10 minuti).
-RetryTimeout
Specifica il tempo, in secondi, in cui il BITS prova a trasferire il file dopo il primo errore. Impostando 0 si evitano i tentativi e si forza il job nello stato BG_JOB_STATE_ERROR quando si verifica un errore. Se il valore del periodo di ripetizione supera l'impostazione del criterio di gruppo JobInactivityTimeout (90 giorni di default), quest'ultimo ha la precedenza e il trasferimento viene cancellato.
Il valore predefinito è 1.209.600 secondi (14 giorni).
-SecurityFlags
Specifica i flag di sicurezza per la richiesta HTTP.
I flag che si possono impostare, a partire dal bit meno significativo, sono i seguenti:
1: Abilita il controllo CRL.
2: Ignora i nomi comuni errati nel certificato del server.
3: Ignora le date errate nel certificato del server.
4: Ignora le autorità di certificazione errate nel certificato del server.
5: Ignora l'uso scorretto del certificato del server.
12: Permette il reindirizzamento da HTTPS a HTTP.
Usa i bit da 9 a 11 per implementare la policy di reindirizzamento:
0,0,0: I reindirizzamenti sono automaticamente permessi.
0,0,1: Il nome remoto è aggiornato se si verifica un reindirizzamento.
0,1,0: Il BITS fallisce se si verifica un reindirizzamento.
-Source
Specifica la posizione di origine e i nomi dei file da trasferire. I nomi dei file di origine sono abbinati ai corrispondenti nomi dei file di destinazione. Per esempio, il primo nome del file specificato nel parametro Source corrisponde al primo nome del file nel parametro Destination, e il secondo nome del file nel parametro Source corrisponde al secondo nome del file nel parametro Destination. I parametri Source e Destination devono avere lo stesso numero di elementi, altrimenti il comando produce un errore. Il parametro accetta i caratteri jolly standard come l'asterisco (*) e il punto interrogativo (?) e anche un'operatore di intervallo come "[a-r]".
-Suspended
Indica che il cmdlet sospende il trasferimento BITS. Se il parametro Suspended non è specificato, il trasferimento viene avviato automaticamente, in caso contrario il prompt dei comandi ritorna immediatamente dopo la creazione del job di trasferimento BITS. Per avviare un trasferimento sospeso si può utilizzare il cmdlet Resume-BitsTransfer.
-TransferPolicy
Specifica, tramite l'utilizzo di una maschera di bit, gli stati di una connessione a consumo in cui il trasferimento può essere pianificato.
I valori accettati per questo parametro sono
- Unrestricted (o unknown): 0x00000001, lo stato dei costi per questa rete a consumo non è noto.
- Capped: 0x00000002, si tratta di una rete a consumo con un piano che ha un limite di utilizzo dei dati.
- BelowCap: 0x00000004, il consumo dati della rete a consumo è al di sotto del limite del piano dati.
- NearCap: 0x00000008, il consumo dati è vicino al limite del piano dati.
- OverCapCharged: 0x00000010, il consumo dati è superiore al limite del piano dati, e l'uso è addebitato.
- OverCapThrottled: 0x00000020, il consumo dati è al di sopra del limite del piano dati, e l'uso è limitato.
- UsageBased: 0x00000040, il consumo dati per questa rete è addebitato in base all'uso.
- Roaming: 0x00000080, il consumo dati per questa rete incorre in costi di roaming. Lo stato dei costi include anche un'opzione (IgnoreCongestion) e un insieme di politiche standard (Uncosted, Standard, NoSurcharge, NotRoaming, e Always) che sono combinazioni di valori di bit discreti.
- IgnoreCongestion: 0x80000000, il trasferimento può essere programmato anche se il fornitore di rete segnala che la rete è congestionata.
- PolicyUnrestricted: 0x80000021, l'insieme degli stati di costo che non consumano la quota di un piano limitato, o incorrono in spese extra.
- Standard: 0x80000067, un insieme di stati di costo adatti a trasferimenti a priorità moderata.
- NoSurcharge: 0x8000006f, l'insieme degli stati di costo che non comportano supplementi per l'uso.
- NotRoaming: 0x8000007f, l'insieme degli stati di costo che escludono lo stato di roaming.
- Always: 0x800000ff, l'insieme di tutti gli stati di costo.
-TransferType
Specifica il tipo di trasferimento dati. I valori accettati per questo parametro sono:
- Download (il valore predefinito): Scarica i file sul computer client.
- Upload: Carica un file sul server.
- UploadReply: Carica un file sul server e riceve un file di risposta dal server.
-UseStoredCredential
Specifica che le credenziali memorizzate nel Windows Credential Manager dovrebbero essere usate per l'autenticazione quando richiesto per il tipo di server di destinazione specificato. Se questo parametro non è specificato e un server richiede l'autenticazione, allora le credenziali esplicite devono essere incluse utilizzando i parametri Credential o ProxyCredential. Questo parametro è un parametro flag i cui valori possono essere sommati per creare il comportamento desiderato.
I valori accettati per questo parametro sono:
- None: Usa solo le credenziali fornite dai parametri Credential o ProxyCredential. Questo è il comportamento predefinito se il parametro non è specificato.
- Proxy: Le credenziali memorizzate nel Windows Credential Manager sono utilizzate per l'autenticazione per qualsiasi server proxy che richiede l'autenticazione. Se nessuna credenziale nel Windows Credential Manager corrisponde al server proxy che necessita di autenticazione, allora è necessario specificare le credenziali utilizzando il parametro ProxyCredential.
- Server: Questo valore non è supportato e genera un errore se specificato.
-WhatIf
Mostra cosa accadrebbe se il cmdlet venisse eseguito. Il cmdlet non viene eseguito.
Esempi
Esempio 1
Start-BitsTransfer -Source "http://server01/servertestdir/testfile1.txt" -Destination "c:\clienttestdir\testfile1.txt"
Crea un job di trasferimento BITS dal server al client.
Poiché il cmdlet Start-BitsTransfer assume che il primo parametro sia l'origine e che il secondo sia la destinazione il comando può essere semplificato in
Start-BitsTransfer "http://server01/servertestdir/testfile1.txt" "c:\clienttestdir\testfile1.txt"
Esempio 2
Import-CSV ElencoFile.txt | Start-BitsTransfer
Questo comando crea job di trasferimento BITS che scaricano più file da un server. Il comando importa le posizioni dei file di origine e di destinazione dal file .txt e poi invia le informazioni al comando Start-BitsTransfer. Il comando Start-BitsTransfer crea un nuovo job di trasferimento BITS per ciascuno dei file in ElencoFile.txt e poi li trasferisce simultaneamente al client.
Il contenuto del file ElencoFile.txt sarà simile a
Source, Destination http://server01/servertestdir/testfile1.txt, c:\clienttestdir\testfile1.txt
Esempio 3
Start-BitsTransfer -Source "c:\clienttestdir\testfile1.txt" -Destination "http://server01/servertestdir/testfile1.txt" -TransferType Upload
Questo comando crea un job di trasferimento BITS che carica un file su un server. I nomi locali e remoti del file sono specificati nei parametri Source e Destination. Poiché il tipo di trasferimento predefinito è Download, il parametro TransferType deve essere impostato su Upload.
Esempio 4
Start-BitsTransfer -Source .\Patch0416.msu -Destination $env:temp\Patch0416.msu -ProxyUsage Override -ProxyList BitsProxy:8080 -ProxyCredential Server01\Admin01
Questo comando usa il cmdlet Start-BitsTransfer per copiare un file patch da un server su una rete a un client su una rete diversa quando le reti sono collegate solo da un server proxy.
Esempio 5
#Percorso e nome del file da scaricare
$url = 'https://images-assets.nasa.gov/video/Seventeen Seconds of Fuel Remained/Seventeen Seconds of Fuel Remained~orig.mp4'
#Path di destinazione
$targetfolder = $env:temp
#Il file verrĂ salvato con lo stesso nome nel percorso di destinazione
$filename = Split-Path -Path $url -Leaf
$targetFile = Join-Path -Path $targetfolder -ChildPath $filename
#avvio trasferimento BITS
Start-BitsTransfer -Source $url -Destination $targetfolder -Description 'Download in corso...' -Priority Low
#Il file video viene visualizzato dal player predefinito
Start-Process -FilePath $targetFile
Lo script sopra riportato provvede a scaricare un video dal sito della NASA e, al termine del download, provvede a visualizzarlo con il player predefinito. Come visibile nello script con il comando Start-BitsTransfer è stata impostata una priorità bassa per il download in modo da poter scaricare il file senza monopolizzare la banda di rete.
 |
| FIG 1 - Start-BitsTransfer |
Esempio 6
$url = 'https://images-assets.nasa.gov/video/Seventeen Seconds of Fuel Remained/Seventeen Seconds of Fuel Remained~orig.mp4'
$targetfolder = $env:temp
Start-BitsTransfer -Source $url -Destination $targetfolder -Asynchronous -Priority Low
Get-BitsTransfer | ForEach-Object {
Write-Warning $_.FileList.RemoteName
$_
} | Where-Object { $_.jobstate -eq 'Transferred' } | ForEach-Object {
#$_ | Select-Object -Property *
$file = $_.FileList.LocalName
Write-Warning "Copia file $file..."
$_ | Complete-BitsTransfer
}
Lo script sopra riportato scarica in bakcground un video dal sito della NASA con bassa priorità e in modalità asincrona. Lo svantaggio dei trasferimenti asincroni del BITS è che i dati vengono scaricati in una cache nascosta e bisogna completare manualmente il trasferimento del file. Tramite Get-BitsTransfer si verificano i job completati quindi il trasferimento del file viene finalizzato utilizzando il cmdlet Complete-BitsTransfer.
Eseguendo PowerShell come amministratore è possibile controllare i trasferimenti BITS iniziati da altri utenti, compreso il sistema operativo utilizzando il cmdlet Get-BitsTransfer.
Get-BitsTransfer -AllUsers
per visualizzare i BITS avviati da altri utenti
Get-BitsTransfer -AllUsers | Select-Object OwnerAccount, Priority, FileList
Per visualizzare maggiori dettagli sui BITS avviati da altri utenti, tra cui priorità e il nome dei file.
 |
| FIG 2 - Get-BitsTransfer |
